Tables

A table is the top-level unit of data organization in Berserk. Each table is an independent collection of logs, traces, and metrics — typically representing a service, environment, or team.

Every cluster comes with a default table ready for ingestion. You can create additional tables to separate data by any boundary that makes sense for your organization.

The table name is the first element of every query:

default
| where level == "ERROR"
| take 10

Listing Tables

bzrk table list

Tables:
  default (ID: 019ae8e5-f2aa-79c2-a0a6-41d49b609f9e)

Creating a Table

bzrk table create myapp

Created table: myapp
  ID: 019cd6a4-ab94-7a90-bcc1-c380ae443daf

Berserk groups a table's rows into chunks by a set of shard fields you choose. A query that then filters a shard field with == or in (…) skips whole chunks instead of scanning them, so choosing shard fields that match how you query a table is one of the biggest levers on query speed.

A newly created table starts with a default shard set tuned for OpenTelemetry-shaped data (the recommended fields below). These are just defaults — replace them with set to match how you query the table when your data is shaped differently.

Set the fields with the CLI. Each is a field=weight pair; a higher weight gives the field more influence on the layout. set replaces the table's fields outright:

bzrk table sharding set myapp \
  "resource.service.name=10 metric_name=10 trace_id=2"

Inspect or remove them:

bzrk table sharding list myapp
bzrk table sharding clear myapp

Recommended fields for OpenTelemetry data

This is the default shard set seeded on every new table — a good starting point for any table carrying OpenTelemetry-shaped logs, traces, and metrics. To re-apply it to an existing table (or after clear):

bzrk table sharding set myapp \
  "metric_name=10 \
   trace_id=2 \
   span_id=1 \
   severity_text=1 \
   resource.service.name=10 \
   resource.service.namespace=1 \
   resource.k8s.deployment.name=5 \
   resource.k8s.namespace.name=1 \
   resource.k8s.pod.name=1 \
   resource.host.name=1"

Note that fields that are configured for sharding but are not present in the row being written or merged do no harm. The set should not exceed ~40 fields.

Shard fields take effect as data is written or re-merged — existing segments are never re-indexed. Changing a table's shard fields affects only newly-ingested data, so the configuration can evolve without rewriting history. (On a long-running cluster sharding list may also show historic field spellings such as metric.name or resource.attributes.service.name, kept to let data flow in both variants for a while. Queries do not rely on the active configuraton, as they read the actual layout in each segment instead.)

Ingest Tokens

An ingest token authenticates an OpenTelemetry Collector and routes its data to a specific table. Each table can have multiple ingest tokens (e.g., one per collector or environment), but each token is bound to exactly one table.

Creating an Ingest Token

bzrk ingest-token create --table myapp my-ingest-token

Created ingest token: my-ingest-token
  ID: 019cd6a6-5fe5-7a80-be74-9dba27894af8
  Table: myapp

  Token: ing_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

  Save this token now — it cannot be retrieved again.

The token value is only displayed at creation time. Store it securely — you will need it to configure your OpenTelemetry Collector.

Listing Ingest Tokens

bzrk ingest-token list

Querying a Table

bzrk search "myapp | take 10" --since "1h ago"

See Query Reference for the full query language reference.