DB
Get started

Operations

System relations

The read-only system relations a NYXDB node registers, grouped by area, with the permission each read needs and the purpose where verified.

System relations are read-only system.<name> relations maintained by the engine. The list below gives every relation with the permission its read needs and its purpose.

How to read them

  • Use an ordinary SELECT, over HTTP or a WebSocket session.
  • Each read needs the listed administrative permission. For several areas an older manage permission (for example credential_manage for system.credentials) still admits the read. Relations marked — have no administrative read action.
  • Rows carry observation fields such as observed_at_millis and freshness_millis.
  • A one-shot read may project columns, filter, order and limit.
  • STREAM SELECT … FROM system.<name> streams a relation, with filters and projections.
SELECT *
FROM system.query_history;
SELECT
  row_id,
  source_relation_id,
  derived_relation_id,
  target_relation_id,
  transformation_revision
FROM system.derived_lineage;
SELECT
  name,
  source_position,
  rows_written,
  completed_rows,
  transformation_revision
FROM system.transformation_revisions;

system.query_history holds the SQL text as executed, so grant telemetry_read only to principals that may see every statement. Credential statements are the exception: history holds only their redacted form.

Catalog and tables

RelationRead permissionPurpose
system.catalog_relations—
system.tables—One row per table, with relation_id and name. SHOW TABLES reads it.
system.table_columns—The columns of each table. DESCRIBE reads it.
system.table_keys—
system.table_attribute_groups—
system.table_indexes—
system.table_index_builds—
system.table_partitions—
system.table_projections—
system.table_storage_plans—
system.table_column_codecs—
system.table_policy_bindings—
system.table_identities—
system.table_tablets—

Views, transformations and lineage

RelationRead permissionPurpose
system.viewsderived_state_read
system.materialized_viewsderived_state_read
system.transformationsderived_state_readOne row per transformation, with derived_relation_id and its declared name.
system.transformation_revisionsderived_state_readOne row per transformation revision: name, source_position, rows_written, completed_rows, condition, health, lag_source_sequences.
system.transformation_frontiersderived_state_readPer source tablet of each transformation: the applied source_sequence, the retained floor and pending outputs.
system.transformation_validationderived_state_read
system.transformation_maintenancetelemetry_read
system.derived_lineagederived_state_readOne row per declared source of each transformation: source, derived and target relation, and the revision.
system.derived_dependenciesderived_state_read
system.derived_authorityderived_state_read
system.derived_operationsderived_state_read

PSI and continuous delivery

RelationRead permissionPurpose
system.psi_streamsarrangement_read
system.psi_arrangementsarrangement_read
system.continuous_sourcesarrangement_read
system.continuous_edge_dead_letterstelemetry_read

Queries and telemetry

RelationRead permissionPurpose
system.queriestelemetry_read
system.query_historytelemetry_readRecent queries: request id, principal, kind, state, status, the full SQL text (not redacted), timings and delivered rows and bytes. Held in process memory, 4,096 entries by default (gateway.observability.query_history_entries), rebuilt empty at restart.
system.query_statstelemetry_readOne row per normalized statement digest: executions, failures, cancellations and timing totals.
system.query_tracestelemetry_read
system.query_telemetry_rollupstelemetry_read
system.query_telemetry_statustelemetry_read
system.query_definition_associationstelemetry_read
system.telemetry_metricstelemetry_read
system.telemetry_eventstelemetry_read
system.telemetry_profilestelemetry_read
system.health_signalstelemetry_read

Settings

RelationRead permissionPurpose
system.settingstelemetry_readOne row per registered setting: name, scope, value, whether it is the default, its source, type, unit, allowed values and documentation fields.

Operations and lifecycle

RelationRead permissionPurpose
system.operationsoperation_readAdministrative operations, kept in a durable journal under the data directory.
system.load_operationstelemetry_read
system.relation_ledgertelemetry_read
system.relation_retirementstelemetry_read
system.bounded_gatestelemetry_read
system.bounded_gate_waitstelemetry_read
system.wal_reclamation_blockerstelemetry_read
system.typed_image_retentiontelemetry_read

Security and governance

RelationRead permissionPurpose
system.database_principalsgovernance_read
system.rolesgovernance_read
system.role_bindingsgovernance_read
system.grantsgovernance_read
system.administrative_grantsgovernance_read
system.credentialsgovernance_readCredentials per principal with their kind and status; no digest, salt or secret.
system.audit_logaudit_read

Federation and applications

RelationRead permissionPurpose
system.application_accessesgovernance_readApplication accesses on a federation host: status, secret generation and grants.
system.sourcestelemetry_readFederation sources on a consumer: endpoint, credential id, lifecycle (ready, paused, unavailable) and the last status.
system.external_relationstelemetry_readExternal relations on a consumer: the host binding, mode and state.
system.application_subscriptionstelemetry_read
system.application_subscription_historytelemetry_read
system.application_usage_directtelemetry_read
system.application_usage_allocatedtelemetry_read
system.application_usage_grosstelemetry_read
system.application_usage_physicaltelemetry_read
system.application_direct_usage_historytelemetry_read
system.usage_rollupstelemetry_read
system.arrangement_usage_historytelemetry_read

Node, storage and replication

RelationRead permissionPurpose
system.cluster_nodestelemetry_read
system.node_servicestelemetry_read
system.node_resourcestelemetry_read
system.resource_allocationstelemetry_read
system.tabletstelemetry_readEach tablet with its relation, owner_epoch and committed_frontier.
system.storagestorage_read
system.storage_policiesstorage_read
system.object_poolsstorage_read
system.index_residencystorage_read
system.tiering_movesstorage_read
system.replicationreplication_read
system.replication_groupsreplication_read
system.replicasreplication_read

The replication, object-pool and tiering relations describe replicas and data placement across nodes; see Deployment topologies.

Lineage and functions

system.derived_lineage holds the lineage of every derived relation, and SHOW FUNCTIONS lists the function library; each function is documented in the function reference.

Profiling

Finding where a NYXDB query spends its time — progress frames, query statistics and EXPLAIN.

Governance

Principals, roles, data grants and administrative permissions on a NYXDB node, and how operators review them.

On this page

How to read themCatalog and tablesViews, transformations and lineagePSI and continuous deliveryQueries and telemetrySettingsOperations and lifecycleSecurity and governanceFederation and applicationsNode, storage and replicationLineage and functions