Skip to content
NOEMATA

Connect a database

ClickHouse is where every table a frame reads lives — your telemetry and Noemata’s own file store. It’s the only supported database today (Apache Doris and DuckDB/SQLite are planned). You configure it under db.clickhouse in noemata.json, and the setup wizard writes that block for you the first time you run noemata config or noemata init.

There are two shapes, and you pick exactly one.

Managed local binary

The default. Noemata downloads a ClickHouse binary and runs it for you — nothing to install, nothing to keep alive. noemata up starts it alongside the rest of the stack.

{ "db": { "clickhouse": { "binary": {} } } }

Every field is optional:

  • version — pin a ClickHouse release instead of the bundled default.
  • http_port / native_port — a number, or "auto" (the default). "auto" binds 8123 / 9000 plus the worktree offset, so parallel worktrees don’t collide.
  • max_memory_gb — cap ClickHouse’s memory.
  • data_dir — where it stores data on disk.

External server or ClickHouse Cloud

Point Noemata at a ClickHouse you already run — a server on your network or ClickHouse Cloud. up won’t try to start or manage it; it only connects.

{
  "db": {
    "clickhouse": {
      "external": { "hosts": "my-clickhouse.example.com", "http_port": 8443 }
    }
  }
}
  • hosts — the ClickHouse host to connect to. Optional; when omitted, Noemata connects to 127.0.0.1 on the configured HTTP port.
  • http_port / native_port — the ports it listens on.

Shared settings

These apply to both shapes:

  • authentication — "none" (the default) leaves ClickHouse open and the app connects anonymously; "password" connects with the database credentials supplied in the environment, and the Noemata UI requires a login.

  • default_database — the database the app binds to and the collector exports into. Defaults to "default".

  • namespace — the prefix of every table Noemata creates for itself: the file store, sessions, and the coordination table with its Keeper path. Defaults to "noemata". Two Noemata deployments share one database by using different namespaces; they still share the telemetry tables, which carry no prefix.

  • request_timeout — maximum dashboard query time in seconds (default 60). The browser aborts the request at this limit. The server also sets ClickHouse’s max_execution_time to the same value.

  • query_settings — a map of ClickHouse settings sent with each dashboard query, such as { "max_threads": 2 }. A max_execution_time value here overrides the server-side limit from request_timeout. The browser timeout remains unchanged. Noemata leaves other ClickHouse performance settings at their defaults.

  • max_server_connections — how many queries the server keeps in flight to ClickHouse at once, across every client it serves. Unset by default, meaning no cap.

    Set this limit when queries contend. In a busy development deployment, the same query took 4.9× longer at the median and 10× longer at p90 with 21 or more concurrent queries than with fewer than 6.

    The limit applies to queries across all clients using the same database address. It includes queries the server relays from browsers and statements the server runs for users. It excludes Noemata’s file-store and session-table queries, autocomplete, and schema lookups. The total connection count can exceed this limit. Queries above the limit wait, and Noemata reports the wait as queue time.

  • max_client_connections — how many queries one client keeps in flight at once: a browser tab, or a single noemata run / noemata validate --online. Unset by default, meaning no cap.

    Use this with max_server_connections to limit one client’s queries. A client is one browser tab or one noemata run / noemata validate --online command. Browsers limit concurrent requests per origin over HTTP/1.1, but not HTTP/2. Autocomplete and schema lookups do not count toward this limit.

The config file contains no credentials. With authentication: "password", set the database username and password in NOEMATA_CH_USERNAME and NOEMATA_CH_PASSWORD. Configure TLS for the Noemata UI separately in the setup wizard.

What ends up in the database

The collector writes telemetry to otel_traces, otel_logs, and the metrics tables (see Send telemetry). Noemata stores its file store, sessions, and coordination table under the configured namespace prefix. Different namespaces keep deployment state separate in a shared database. Frames query telemetry through semantic-layer views installed by integrations. For example, a frame can select DurationP95 instead of a raw column.

The full db schema, including every field above, is in the project config reference.