GraphQL Operations and Types

This contract snapshot covers the SemanticFed fields and product types in the service schema reviewed on 2026-11-01 (source revision eb9ae915967929ce19bf55123a8003273a072d53). It is a reference for constructing operations, not a claim that every connector kind has an executable adapter or that every environment is currently serving the service.

Use the GraphQL API guide for both authentication tokens, workspace context, pagination, and error handling. Operation signatures below are not complete requests: wrap selected fields in a query or mutation and select output subfields where required. Passing an ID does not grant access to another workspace or resource.

Queries and mutations

Query

semConnector

semConnector(id: ID!): SemConnector @rbac(action: "read", resource: "semanticfed-connector", resourceIdArg: "id", scopeType: "wspace")

semDataSource

semDataSource(id: ID!): SemDataSource @rbac(action: "read", resource: "semanticfed-data-source", resourceIdArg: "id", scopeType: "wspace")

semEntity

semEntity(id: ID!): SemEntity @rbac(action: "read", resource: "semanticfed-entity", resourceIdArg: "id", scopeType: "wspace")

semHealth

Liveness/identity probe for the SemanticFed subgraph.

semHealth: String! @rbac(public: true, scopeType: "wspace")

semLineage

End-to-end lineage for the calling workspace. With rootKind + rootId, returns the lineage of that record: UPSTREAM for where its data comes from, DOWNSTREAM for what depends on it, BOTH (default) for both. Without a root, returns the whole-workspace lineage graph. depth limits the hops from the root (1–20; unbounded when omitted).

semLineage(depth: Int, direction: SemLineageDirection = BOTH, rootId: ID, rootKind: SemLineageRootKind): SemLineageGraph! @rbac(action: "read", resource: "semanticfed-model", scopeType: "wspace")

semListAccessPolicies

semListAccessPolicies(entityId: ID, modelId: ID): [SemAccessPolicy!]! @rbac(action: "read", resource: "semanticfed-access-policy", scopeType: "wspace")

semListConnections

semListConnections(dataSourceId: ID!): [SemConnection!]! @rbac(action: "read", resource: "semanticfed-connection", scopeType: "wspace")

semListConnectors

semListConnectors(kind: SemConnectorKind, pagination: PaginationInput): SemConnectorConnection! @rbac(action: "read", resource: "semanticfed-connector", scopeType: "wspace")

semListDataSources

semListDataSources(connectorId: ID, pagination: PaginationInput, status: SemDataSourceStatus): SemDataSourceConnection! @rbac(action: "read", resource: "semanticfed-data-source", scopeType: "wspace")

semListEntities

semListEntities(modelId: ID!): [SemEntity!]! @rbac(action: "read", resource: "semanticfed-entity", scopeType: "wspace")

semListModels

semListModels(pagination: PaginationInput, status: SemModelStatus): SemSemanticModelConnection! @rbac(action: "read", resource: "semanticfed-model", scopeType: "wspace")

semListQueries

semListQueries(modelId: ID, pagination: PaginationInput, status: SemQueryStatus): SemQueryConnection! @rbac(action: "read", resource: "semanticfed-query", scopeType: "wspace")

semListQueryRuns

semListQueryRuns(pagination: PaginationInput, queryId: ID!, status: SemQueryRunStatus): SemQueryRunConnection! @rbac(action: "read", resource: "semanticfed-query-run", scopeType: "wspace")

semListRelationships

semListRelationships(modelId: ID!): [SemRelationship!]! @rbac(action: "read", resource: "semanticfed-relationship", scopeType: "wspace")

semModel

semModel(id: ID!): SemSemanticModel @rbac(action: "read", resource: "semanticfed-model", resourceIdArg: "id", scopeType: "wspace")

semNlSettings

The workspace's settings for natural-language questions (LLM-assisted phrasing is off until enabled).

semNlSettings: SemNlSettings! @rbac(action: "read", resource: "semanticfed-model", scopeType: "wspace")

semOnboardingProgress

Getting-started checklist progress for the calling workspace, derived from the records the workspace actually holds (so it persists across sessions and devices).

semOnboardingProgress: SemOnboardingProgress! @rbac(action: "read", resource: "semanticfed-connector", scopeType: "wspace")

semQuery

semQuery(id: ID!): SemQuery @rbac(action: "read", resource: "semanticfed-query", resourceIdArg: "id", scopeType: "wspace")

semQueryRun

A single query run by id (workspace-scoped). Poll this after semRunQuery: runs execute asynchronously and move QUEUED -> PLANNING -> RUNNING -> SUCCEEDED/FAILED.

semQueryRun(id: ID!): SemQueryRun @rbac(action: "read", resource: "semanticfed-query-run", scopeType: "wspace")

semQueryRunResult

The governed result rows of a SUCCEEDED query run, paginated with pagination.limit (default 100, max 500) and pagination.offset (use the previous page's nextOffset). Only the actor the run executed for can read its rows: they are the output of that actor's access-policy evaluation. Any other caller gets NOT_FOUND.

semQueryRunResult(pagination: PaginationInput, runId: ID!): SemQueryRunResult! @rbac(action: "read", resource: "semanticfed-query-run", scopeType: "wspace")

semSqlCatalog

The SQL view of a semantic model: one table per entity, one column per dimension and metric. modelId is optional when the workspace has one model.

semSqlCatalog(modelId: ID): SemSqlCatalog! @rbac(action: "read", resource: "semanticfed-model", scopeType: "wspace")

semTranslateQuestion

Translate a natural-language question into SQL over a semantic model without running it: the interpretation steps, generated SQL, confidence and, when the question cannot be answered as asked, a clarification and suggestions. Reads no data and is not metered as a query run; when LLM-assisted phrasing is on and the workspace's AI provider is asked, that counts as one AI operation.

semTranslateQuestion(input: SemNlQuestionInput!): SemNlTranslation! @rbac(action: "read", resource: "semanticfed-model", scopeType: "wspace")

Mutation

semArchiveConnector

semArchiveConnector(id: ID!): Boolean! @rbac(action: "delete", resource: "semanticfed-connector", resourceIdArg: "id", scopeType: "wspace")

semArchiveDataSource

semArchiveDataSource(id: ID!): Boolean! @rbac(action: "delete", resource: "semanticfed-data-source", resourceIdArg: "id", scopeType: "wspace")

semArchiveModel

semArchiveModel(id: ID!): Boolean! @rbac(action: "delete", resource: "semanticfed-model", resourceIdArg: "id", scopeType: "wspace")

semArchiveQuery

semArchiveQuery(id: ID!): Boolean! @rbac(action: "delete", resource: "semanticfed-query", resourceIdArg: "id", scopeType: "wspace")

semAskQuestion

Answer a natural-language question: translate it into SQL over the semantic model and execute it through the SQL endpoint with the caller's access policies enforced (ROW filters, COLUMN masks, ENTITY denials). Questions that need clarification return the translation with result = null and run nothing. Each question counts as one federated query run against the plan quota.

semAskQuestion(input: SemNlQuestionInput!): SemNlAnswer! @rbac(action: "execute", resource: "semanticfed-query", scopeType: "wspace") @usage(productId: "semanticfed", quotaName: "semanticfed.query_runs.monthly", amount: 1, description: "Natural-language question", checkQuota: true, trackUsage: true)

semCreateAccessPolicy

semCreateAccessPolicy(input: SemCreateAccessPolicyInput!): SemAccessPolicy! @rbac(action: "create", resource: "semanticfed-access-policy", scopeType: "wspace")

semCreateConnector

semCreateConnector(input: SemCreateConnectorInput!): SemConnector! @rbac(action: "create", resource: "semanticfed-connector", scopeType: "wspace") @usage(productId: "semanticfed", quotaName: "semanticfed.connectors.count", amount: 1, description: "Connector registered", checkQuota: true, trackUsage: true)

semCreateDataSource

semCreateDataSource(input: SemCreateDataSourceInput!): SemDataSource! @rbac(action: "create", resource: "semanticfed-data-source", scopeType: "wspace") @usage(productId: "semanticfed", quotaName: "semanticfed.sources.count", amount: 1, description: "Data source connected", checkQuota: true, trackUsage: true)

semCreateDimension

semCreateDimension(input: SemCreateDimensionInput!): SemDimension! @rbac(action: "create", resource: "semanticfed-dimension", scopeType: "wspace")

semCreateEntity

semCreateEntity(input: SemCreateEntityInput!): SemEntity! @rbac(action: "create", resource: "semanticfed-entity", scopeType: "wspace")

semCreateMetric

semCreateMetric(input: SemCreateMetricInput!): SemMetric! @rbac(action: "create", resource: "semanticfed-metric", scopeType: "wspace")

semCreateModel

semCreateModel(input: SemCreateModelInput!): SemSemanticModel! @rbac(action: "create", resource: "semanticfed-model", scopeType: "wspace") @usage(productId: "semanticfed", quotaName: "semanticfed.models.count", amount: 1, description: "Semantic model created", checkQuota: true, trackUsage: true)

semCreateQuery

semCreateQuery(input: SemCreateQueryInput!): SemQuery! @rbac(action: "create", resource: "semanticfed-query", scopeType: "wspace")

semCreateRelationship

semCreateRelationship(input: SemCreateRelationshipInput!): SemRelationship! @rbac(action: "create", resource: "semanticfed-relationship", scopeType: "wspace")

semDeleteEntity

semDeleteEntity(id: ID!): Boolean! @rbac(action: "delete", resource: "semanticfed-entity", resourceIdArg: "id", scopeType: "wspace")

semExecuteSql

Execute one read-only SQL SELECT against a semantic model and return the governed rows synchronously. Writes, multiple statements and unsupported SQL are rejected with BAD_USER_INPUT; access-policy denials with FORBIDDEN. Each statement counts as one federated query run against the plan quota.

semExecuteSql(input: SemExecuteSqlInput!): SemSqlResult! @rbac(action: "execute", resource: "semanticfed-query", scopeType: "wspace") @usage(productId: "semanticfed", quotaName: "semanticfed.query_runs.monthly", amount: 1, description: "Federated SQL statement", checkQuota: true, trackUsage: true)

semPublishModel

Publish a draft model — bumps its version and flips status to PUBLISHED.

semPublishModel(id: ID!): SemSemanticModel! @rbac(action: "update", resource: "semanticfed-model", resourceIdArg: "id", scopeType: "wspace")

semPublishQuery

Publish a saved query. A query is published once; publishing it again is a CONFLICT. Each published query holds a published-query slot until it is archived.

semPublishQuery(id: ID!): SemQuery! @rbac(action: "update", resource: "semanticfed-query", resourceIdArg: "id", scopeType: "wspace") @usage(productId: "semanticfed", quotaName: "semanticfed.queries.published", amount: 1, description: "Federated query published", checkQuota: true, trackUsage: true)

semRecordConnection

Record a connection health probe for a data source and reconcile its status.

semRecordConnection(input: SemRecordConnectionInput!): SemConnection! @rbac(action: "create", resource: "semanticfed-connection", scopeType: "wspace")

semRemoveWorkspaceDemoData

Remove every demo record created by semSeedWorkspaceDemoData from the calling workspace. The user's own records are never touched.

semRemoveWorkspaceDemoData: SemRemoveWorkspaceDemoDataResult! @rbac(action: "delete", resource: "semanticfed-connector", scopeType: "wspace")

semRunQuery

Enqueue a federated execution of a saved query; returns the new run record in QUEUED status immediately. An async worker plans and executes it — poll semQueryRun(id) for the final status, plan summary and metrics.

semRunQuery(id: ID!): SemQueryRun! @rbac(action: "execute", resource: "semanticfed-query", resourceIdArg: "id", scopeType: "wspace") @usage(productId: "semanticfed", quotaName: "semanticfed.query_runs.monthly", amount: 1, description: "Federated query run", checkQuota: true, trackUsage: true)

semSeedWorkspaceDemoData

Seed the calling workspace with a labelled demo set: a sample Postgres connector and data source, a published semantic model (customers and orders, with dimensions, metrics and a relationship) and a saved query. Idempotent: a second call returns the existing demo records.

semSeedWorkspaceDemoData: SemSeedWorkspaceDemoDataResult! @rbac(action: "create", resource: "semanticfed-connector", scopeType: "wspace")

semSetAccessPolicyActive

semSetAccessPolicyActive(id: ID!, isActive: Boolean!): SemAccessPolicy! @rbac(action: "update", resource: "semanticfed-access-policy", resourceIdArg: "id", scopeType: "wspace")

semTransitionDataSource

Move a data source through its connectivity lifecycle (validated transitions).

semTransitionDataSource(id: ID!, status: SemDataSourceStatus!): SemDataSource! @rbac(action: "update", resource: "semanticfed-data-source", resourceIdArg: "id", scopeType: "wspace")

semUpdateConnector

semUpdateConnector(id: ID!, input: SemUpdateConnectorInput!): SemConnector! @rbac(action: "update", resource: "semanticfed-connector", resourceIdArg: "id", scopeType: "wspace")

semUpdateDataSource

semUpdateDataSource(id: ID!, input: SemUpdateDataSourceInput!): SemDataSource! @rbac(action: "update", resource: "semanticfed-data-source", resourceIdArg: "id", scopeType: "wspace")

semUpdateEntity

semUpdateEntity(id: ID!, input: SemUpdateEntityInput!): SemEntity! @rbac(action: "update", resource: "semanticfed-entity", resourceIdArg: "id", scopeType: "wspace")

semUpdateModel

semUpdateModel(id: ID!, input: SemUpdateModelInput!): SemSemanticModel! @rbac(action: "update", resource: "semanticfed-model", resourceIdArg: "id", scopeType: "wspace")

semUpdateNlSettings

Replace the workspace's settings for natural-language questions. Turning on LLM-assisted phrasing requires an OpenAI or Anthropic connection of this workspace (created in Integrations); the connection is checked when saved. Governance-level permission: it decides which provider sees the model's vocabulary and the questions that need help.

semUpdateNlSettings(input: SemUpdateNlSettingsInput!): SemNlSettings! @rbac(action: "update", resource: "semanticfed-access-policy", scopeType: "wspace")

semUpdateQuery

semUpdateQuery(id: ID!, input: SemUpdateQueryInput!): SemQuery! @rbac(action: "update", resource: "semanticfed-query", resourceIdArg: "id", scopeType: "wspace")

Product types

These declarations describe input fields, enum values, and selected response shapes. They are schema definitions, not requests to execute. Shared scalars such as JSON, DateTime, and ID follow the platform API contract.

SemAccessPolicy

"""
A governed access rule enforced by the federated query engine at query time,
for the actor each query run executes for. DENY overrides ALLOW; ALLOW
policies are allow-lists for their scope (once an entity has an ALLOW policy of
a scope, actors it does not match lose that access). Every run records its
policy decisions on SemQueryRun.planSummary.governance.
"""
type SemAccessPolicy @key(fields: "id") {
  createdAt: DateTime!
  description: String
  effect: SemPolicyEffect!
  """Limit the policy to one entity (null = every entity in scope)."""
  entityId: ID
  id: ID!
  isActive: Boolean!
  """
  Limit the policy to one semantic model (null = every model in the workspace).
  """
  modelId: ID
  name: String!
  """
  Who the policy applies to: "*" (everyone), "actor:<id>" / "user:<id>", or
  "role:<name-or-id>" (the actor's workspace roles).
  """
  principal: String!
  """
  Scope-specific rule. ROW: {"conditions":[{"field","op","value"|"valueFrom":"actor.id"}]}
  (AND-ed; empty = every row). COLUMN: {"columns":[...],"mask":"NULL"|"REDACT"|"HASH"}.
  ENTITY: {}.
  """
  rule: JSON
  scope: SemPolicyScope!
  updatedAt: DateTime!
  workspaceId: ID!
}

SemAggregation

enum SemAggregation {
  AVG
  COUNT
  COUNT_DISTINCT
  CUSTOM
  MAX
  MEDIAN
  MIN
  SUM
}

SemConnection

type SemConnection @key(fields: "id") {
  createdAt: DateTime!
  dataSourceId: ID!
  health: SemConnectionHealth!
  id: ID!
  latencyMs: Int
  message: String
  probedAt: DateTime!
  updatedAt: DateTime!
  workspaceId: ID!
}

SemConnectionHealth

enum SemConnectionHealth {
  DEGRADED
  HEALTHY
  UNKNOWN
  UNREACHABLE
}

SemConnector

type SemConnector @key(fields: "id") {
  capabilities: JSON
  createdAt: DateTime!
  dataSources: [SemDataSource!]!
  description: String
  id: ID!
  isActive: Boolean!
  kind: SemConnectorKind!
  name: String!
  updatedAt: DateTime!
  workspaceId: ID!
}

SemConnectorConnection

type SemConnectorConnection {
  items: [SemConnector!]!
  pageInfo: SemPageInfo!
}

SemConnectorKind

enum SemConnectorKind {
  BIGQUERY
  CLICKHOUSE
  DATABRICKS
  GRAPHQL_API
  MONGODB
  MYSQL
  OTHER
  POSTGRES
  REDSHIFT
  REST_API
  S3_PARQUET
  SNOWFLAKE
}

SemCreateAccessPolicyInput

input SemCreateAccessPolicyInput {
  description: String
  effect: SemPolicyEffect = ALLOW
  entityId: ID
  modelId: ID
  name: String!
  principal: String!
  rule: JSON
  scope: SemPolicyScope = ROW
}

SemCreateConnectorInput

input SemCreateConnectorInput {
  capabilities: JSON
  description: String
  kind: SemConnectorKind = POSTGRES
  name: String!
}

SemCreateDataSourceInput

input SemCreateDataSourceInput {
  connectorId: ID!
  description: String
  endpoint: JSON
  name: String!
  pushdownEnabled: Boolean = true
  """
  Reference to the credential this data source connects with; the credential itself is never stored or returned.
  One of: NAME or env://NAME (workspace-scoped environment variable), aws-sm://<name>[#<key>] (AWS Secrets Manager
  secret provisioned for this workspace, optionally one key of a JSON secret) or vault://<mount>/<path>#<key>
  (HashiCorp Vault KV v2 entry provisioned for this workspace). References always resolve inside the owning workspace.
  """
  secretRef: String
  tags: [String!]
}

SemCreateDimensionInput

input SemCreateDimensionInput {
  dataType: SemDataType = STRING
  description: String
  entityId: ID!
  expression: String
  isPrimary: Boolean = false
  name: String!
}

SemCreateEntityInput

input SemCreateEntityInput {
  dataSourceId: ID
  description: String
  kind: SemEntityKind = TABLE
  modelId: ID!
  name: String!
  physicalName: String
  primaryKey: String
  sqlDefinition: String
}

SemCreateMetricInput

input SemCreateMetricInput {
  aggregation: SemAggregation = SUM
  description: String
  entityId: ID!
  expression: String
  format: String
  name: String!
}

SemCreateModelInput

input SemCreateModelInput {
  description: String
  name: String!
  tags: [String!]
}

SemCreateQueryInput

input SemCreateQueryInput {
  cacheTtlSeconds: Int
  cacheable: Boolean = true
  description: String
  modelId: ID
  name: String!
  parameters: JSON
  queryText: String!
  tags: [String!]
}

SemCreateRelationshipInput

input SemCreateRelationshipInput {
  description: String
  fromEntityId: ID!
  fromField: String!
  kind: SemRelationshipKind = MANY_TO_ONE
  modelId: ID!
  name: String!
  toEntityId: ID!
  toField: String!
}

SemDataSource

type SemDataSource @key(fields: "id") {
  connections: [SemConnection!]!
  connector: SemConnector
  connectorId: ID!
  createdAt: DateTime!
  description: String
  endpoint: JSON
  id: ID!
  lastIntrospectedAt: DateTime
  name: String!
  pushdownEnabled: Boolean!
  """
  Reference to the credential this data source connects with; the credential itself is never stored or returned.
  One of: NAME or env://NAME (workspace-scoped environment variable), aws-sm://<name>[#<key>] (AWS Secrets Manager
  secret provisioned for this workspace, optionally one key of a JSON secret) or vault://<mount>/<path>#<key>
  (HashiCorp Vault KV v2 entry provisioned for this workspace). References always resolve inside the owning workspace.
  """
  secretRef: String
  status: SemDataSourceStatus!
  tags: [String!]!
  updatedAt: DateTime!
  workspaceId: ID!
}

SemDataSourceConnection

type SemDataSourceConnection {
  items: [SemDataSource!]!
  pageInfo: SemPageInfo!
}

SemDataSourceStatus

enum SemDataSourceStatus {
  CONNECTED
  DEGRADED
  DISABLED
  DISCONNECTED
  DRAFT
}

SemDataType

enum SemDataType {
  BOOLEAN
  DATE
  DECIMAL
  GEO
  INTEGER
  JSON
  STRING
  TIMESTAMP
}

SemDimension

type SemDimension @key(fields: "id") {
  createdAt: DateTime!
  dataType: SemDataType!
  description: String
  entityId: ID!
  expression: String
  id: ID!
  isPrimary: Boolean!
  name: String!
  updatedAt: DateTime!
  workspaceId: ID!
}

SemEntity

type SemEntity @key(fields: "id") {
  createdAt: DateTime!
  dataSourceId: ID
  description: String
  dimensions: [SemDimension!]!
  id: ID!
  kind: SemEntityKind!
  metrics: [SemMetric!]!
  modelId: ID!
  name: String!
  physicalName: String
  primaryKey: String
  sqlDefinition: String
  updatedAt: DateTime!
  workspaceId: ID!
}

SemEntityKind

enum SemEntityKind {
  DERIVED
  EXTERNAL
  TABLE
  VIEW
}

SemExecuteSqlInput

input SemExecuteSqlInput {
  """
  Maximum rows returned (default 1000, max 10000). truncated = true when more matched.
  """
  maxRows: Int
  """
  Semantic model the SQL runs against. Optional when the workspace has exactly one model.
  """
  modelId: ID
  """
  One read-only SELECT statement. Tables are the model's entities, columns
  their dimensions and metrics. Supported: SELECT [DISTINCT], *, table.*,
  SUM/AVG/MIN/MAX/COUNT/COUNT(DISTINCT), [INNER] JOIN ... ON a = b,
  WHERE ... AND ..., GROUP BY (columns or positions), ORDER BY ... ASC|DESC,
  LIMIT, OFFSET, quoted identifiers, aliases, comments and a trailing ';'.
  """
  sql: String!
  """
  Execution time limit in milliseconds (default 30000, min 1000, max 60000).
  """
  timeoutMs: Int
}

SemLineageDirection

enum SemLineageDirection {
  BOTH
  """What depends on the root (impact analysis)."""
  DOWNSTREAM
  """Where the root's data comes from."""
  UPSTREAM
}

SemLineageEdge

type SemLineageEdge {
  """
  How the downstream node uses the upstream one, e.g. 'SELECT (revenue: SUM), GROUP BY'.
  """
  detail: String
  """Upstream node id."""
  from: ID!
  id: ID!
  kind: SemLineageEdgeKind!
  """
  For EXECUTED_ON edges: when the run that read the data source finished.
  """
  observedAt: DateTime
  """Downstream node id."""
  to: ID!
}

SemLineageEdgeKind

"""
The relation an edge records. Every edge points downstream, in the direction
data flows.
"""
enum SemLineageEdgeKind {
  """Entity → one of its dimensions, metrics or unregistered columns."""
  DEFINES
  """Data source → a saved query whose latest successful run read from it."""
  EXECUTED_ON
  """Data source → a physical table it holds."""
  HOSTS
  """
  Entity → entity joined to it by a model relationship (context, not data flow).
  """
  JOINS
  """
  Physical table (or the data source itself, for an entity without a table) → entity.
  """
  MAPS_TO
  """Entity → the semantic model it belongs to."""
  MEMBER_OF
  """Connector → a data source that instantiates it."""
  PROVIDES
  """Entity, dimension, metric or column → a saved query that reads it."""
  READ_BY
  """Semantic model → a saved query bound to it."""
  SERVES
}

SemLineageGraph

type SemLineageGraph {
  direction: SemLineageDirection!
  edges: [SemLineageEdge!]!
  nodes: [SemLineageNode!]!
  """
  The node the traversal started from; null for the whole-workspace graph.
  """
  rootId: ID
  """
  True when the workspace is larger than one lineage pass reads, or the node cap was reached.
  """
  truncated: Boolean!
  warnings: [SemLineageWarning!]!
}

SemLineageNode

type SemLineageNode {
  """
  Kind-specific detail: connector kind, physical name, field expression, model name.
  """
  detail: String
  """
  Stable node id, e.g. ENTITY:<entityId> or TABLE:<dataSourceId>:<schema.table>.
  """
  id: ID!
  kind: SemLineageNodeKind!
  label: String!
  """
  The containing node: the data source of a table, the entity of a field, the model of an entity.
  """
  parentId: ID
  """
  The SemanticFed record behind the node; null for TABLE and COLUMN nodes.
  """
  refId: ID
  """
  Kind-specific status: data source status, model status, entity kind, field data type.
  """
  status: String
}

SemLineageNodeKind

"""The kind of a node in a lineage graph."""
enum SemLineageNodeKind {
  """
  A field a query reads that is not a registered dimension or metric (read as a physical column).
  """
  COLUMN
  CONNECTOR
  DATA_SOURCE
  DIMENSION
  ENTITY
  METRIC
  MODEL
  QUERY
  """
  A physical table or view in a data source, read by one or more entities.
  """
  TABLE
}

SemLineageRootKind

"""The record kinds a lineage traversal can start from."""
enum SemLineageRootKind {
  CONNECTOR
  DATA_SOURCE
  DIMENSION
  ENTITY
  METRIC
  MODEL
  QUERY
}

SemLineageWarning

"""Broken or incomplete lineage found while computing the graph."""
type SemLineageWarning {
  message: String!
  """
  The node the warning is about; null for a warning about the whole graph.
  """
  nodeId: ID
}

SemMetric

type SemMetric @key(fields: "id") {
  aggregation: SemAggregation!
  createdAt: DateTime!
  description: String
  entityId: ID!
  expression: String
  format: String
  id: ID!
  name: String!
  updatedAt: DateTime!
  workspaceId: ID!
}

SemModelStatus

enum SemModelStatus {
  ARCHIVED
  DEPRECATED
  DRAFT
  PUBLISHED
}

SemNlAnswer

type SemNlAnswer {
  """The governed result rows (null when the question needs clarification)."""
  result: SemSqlResult
  translation: SemNlTranslation!
}

SemNlAssistStatus

"""
Whether and how the workspace's own AI provider helped answer a question (LLM-assisted phrasing, BYOK).
"""
enum SemNlAssistStatus {
  """LLM-assisted phrasing is turned off for this workspace."""
  DISABLED
  """
  The workspace's AI provider connection is missing, revoked, or not a supported provider.
  """
  NOT_CONFIGURED
  """
  The deterministic translator answered, or the question cannot be fixed by rewording it.
  """
  NOT_NEEDED
  """
  The provider was asked, but its rewrite could not be answered from the model either.
  """
  NO_IMPROVEMENT
  """
  The AI provider could not be reached, refused the key, or returned an error.
  """
  PROVIDER_ERROR
  """The workspace has used all of today's AI operations."""
  QUOTA_EXHAUSTED
  """
  The AI-operation quota is not provisioned for this workspace or could not be checked, so the provider was not called.
  """
  QUOTA_UNAVAILABLE
  """
  The provider reworded the question with the model's names, and the translator answered the rewrite.
  """
  REPHRASED
  """
  The question asked for the deterministic translator only (allowAssist: false).
  """
  SKIPPED
}

SemNlClarificationReason

enum SemNlClarificationReason {
  EMPTY_QUESTION
  """A filter value does not fit the column's data type."""
  INVALID_FILTER
  """The interpretation did not produce a valid statement for the model."""
  INVALID_QUERY
  """
  Too much of the question matches nothing in the model to answer it reliably.
  """
  LOW_CONFIDENCE
  """
  The question combines entities that no relationship of the model connects.
  """
  NO_JOIN_PATH
  """
  Nothing in the question names an entity, dimension or metric of the model.
  """
  NO_MATCH
  TOO_LONG
  """
  A follow-up names a value (for example 'only EU') without a column the conversation lets it apply to.
  """
  UNPLACED_VALUE
  """
  The question needs an aggregation the engine does not support (for example a MEDIAN metric).
  """
  UNSUPPORTED_AGGREGATION
}

SemNlQuestionInput

input SemNlQuestionInput {
  """
  Set to false to answer with the deterministic translator only, even when LLM-assisted phrasing is on.
  """
  allowAssist: Boolean
  """
  Earlier questions of the same conversation, oldest first (the last 10 are
  used). A follow-up such as "and by status?", "only EU" or "top 3 instead"
  refines the interpretation of these questions; a question that stands on its
  own starts a new interpretation.
  """
  history: [String!]
  """Maximum rows returned (default 1000, max 10000)."""
  maxRows: Int
  """
  Semantic model to ask. Optional when the workspace has exactly one model.
  """
  modelId: ID
  """
  The question in plain English, for example: top 5 regions by revenue where status is 'paid'.
  """
  question: String!
  """
  Execution time limit in milliseconds (default 30000, min 1000, max 60000).
  """
  timeoutMs: Int
}

SemNlSettings

"""Workspace settings for natural-language questions."""
type SemNlSettings {
  """
  wspace-integrations connection holding the workspace's AI provider key. The key itself is never stored or returned by SemanticFed.
  """
  aiConnectionId: ID
  """Provider model to use; null means defaultAiModel."""
  aiModel: String
  """Provider of that connection (openai or anthropic)."""
  aiProviderKey: String
  """The model used when aiModel is null."""
  defaultAiModel: String
  """
  When true, a question the deterministic translator cannot answer (NO_MATCH or
  LOW_CONFIDENCE) is reworded by the workspace's own AI provider and translated
  again. Each provider call counts as one AI operation.
  """
  llmAssistEnabled: Boolean!
  """Integration providers that can be used for LLM-assisted phrasing."""
  supportedProviders: [String!]!
  updatedAt: DateTime
  updatedBy: String
}

SemNlStatus

enum SemNlStatus {
  """
  The question could not be answered as asked; see clarificationReason and suggestions. Nothing was run.
  """
  NEEDS_CLARIFICATION
  """The question was translated into SQL (semAskQuestion also ran it)."""
  TRANSLATED
}

SemNlStep

"""
One decision the translator made, in the order it applies to the query.
"""
type SemNlStep {
  """SUM, AVG, MIN, MAX, COUNT or COUNT_DISTINCT (MEASURE steps)."""
  aggregation: String
  """Row limit (LIMIT steps)."""
  count: Int
  """ASC or DESC (ORDER steps)."""
  direction: String
  entity: String
  field: String
  """
  True when the aggregation is the metric's governed aggregation rather than one the question chose.
  """
  governed: Boolean!
  kind: SemNlStepKind!
  """Comparison operator (FILTER steps)."""
  operator: String
  """Relationship followed (JOIN steps)."""
  relationship: String
  """Comparison value (FILTER steps)."""
  value: JSON
}

SemNlStepKind

enum SemNlStepKind {
  """A column returned as is."""
  COLUMN
  """The entity the query reads from."""
  ENTITY
  FILTER
  GROUP_BY
  """An entity joined through a model relationship."""
  JOIN
  LIMIT
  """
  An aggregated value (a governed metric, or an aggregation the question asked for).
  """
  MEASURE
  ORDER
}

SemNlTranslation

type SemNlTranslation {
  """Whether and how the workspace's AI provider helped."""
  assist: SemNlAssistStatus!
  """The AI provider that was asked (openai or anthropic), when one was."""
  assistProvider: String
  """Translated explanation of what to change (NEEDS_CLARIFICATION only)."""
  clarification: String
  clarificationReason: SemNlClarificationReason
  """
  Share of the question's meaningful words grounded in the model, from 0 to 1.
  """
  confidence: Float!
  """
  Translation engine that produced the answer: semantic-parser-v1, or semantic-parser-v1+llm-rephrase when the AI provider's rewrite was answered.
  """
  engine: String!
  """
  True when the question was answered as a follow-up of the earlier questions in history.
  """
  followUp: Boolean!
  modelId: ID!
  modelName: String!
  question: String!
  """
  The AI provider's rewrite of the question, when one was produced. The provider never writes SQL; the rewrite is translated like any question.
  """
  rephrasedQuestion: String
  """
  The generated read-only SQL statement (TRANSLATED only). It can be edited and run with semExecuteSql.
  """
  sql: String
  status: SemNlStatus!
  steps: [SemNlStep!]!
  """Example questions this model can answer."""
  suggestions: [String!]!
  """
  Words of the question that match nothing in the model and were ignored.
  """
  unmatchedTerms: [String!]!
}

SemOnboardingProgress

type SemOnboardingProgress {
  completedCount: Int!
  """True while the workspace still holds the getting-started demo data."""
  demoDataPresent: Boolean!
  isComplete: Boolean!
  steps: [SemOnboardingStep!]!
  totalCount: Int!
  workspaceId: ID!
}

SemOnboardingStep

"""
One getting-started step. A step is complete once the workspace holds at least
one record of the matching kind that the user created themselves; records added
by the demo-data seed are never counted.
"""
type SemOnboardingStep {
  completed: Boolean!
  """How many of the user's own records satisfy this step."""
  count: Int!
  key: SemOnboardingStepKey!
}

SemOnboardingStepKey

"""
The getting-started steps a new SemanticFed workspace works through, in order.
"""
enum SemOnboardingStepKey {
  ADD_DATA_SOURCE
  ADD_POLICY
  CREATE_MODEL
  DEFINE_METRIC
  REGISTER_CONNECTOR
  RUN_QUERY
}

SemPageInfo

type SemPageInfo {
  cursor: String
  hasMore: Boolean!
}

SemPolicyEffect

enum SemPolicyEffect {
  ALLOW
  DENY
}

SemPolicyScope

enum SemPolicyScope {
  COLUMN
  ENTITY
  ROW
}

SemQuery

type SemQuery @key(fields: "id") {
  cacheTtlSeconds: Int!
  cacheable: Boolean!
  createdAt: DateTime!
  description: String
  id: ID!
  modelId: ID
  name: String!
  parameters: JSON
  queryText: String!
  runs: [SemQueryRun!]!
  status: SemQueryStatus!
  tags: [String!]!
  updatedAt: DateTime!
  workspaceId: ID!
}

SemQueryConnection

type SemQueryConnection {
  items: [SemQuery!]!
  pageInfo: SemPageInfo!
}

SemQueryRun

type SemQueryRun @key(fields: "id") {
  createdAt: DateTime!
  durationMs: Int
  errorMessage: String
  finishedAt: DateTime
  fromCache: Boolean!
  id: ID!
  planSummary: JSON
  queryId: ID!
  rowCount: Int
  runById: ID
  sourcesTouched: Int!
  startedAt: DateTime
  status: SemQueryRunStatus!
  updatedAt: DateTime!
  workspaceId: ID!
}

SemQueryRunConnection

type SemQueryRunConnection {
  items: [SemQueryRun!]!
  pageInfo: SemPageInfo!
}

SemQueryRunResult

"""
A page of the governed result of a SUCCEEDED query run: the rows exactly as the
federated engine produced them for the run's actor, with ROW access policies
already filtered and COLUMN masks already applied. Results are stored up to a
cap (10,000 rows / 5 MiB by default; truncated = true when the full result was
larger) and kept for a retention window (7 days by default, see expiresAt).
"""
type SemQueryRunResult {
  columns: [SemQueryRunResultColumn!]!
  """When the stored result is deleted; run the query again afterwards."""
  expiresAt: DateTime!
  """Page size used (default 100, max 500)."""
  limit: Int!
  """
  Offset of the next page (pass it as pagination.offset), or null on the last page.
  """
  nextOffset: Int
  """Offset of the first row of this page."""
  offset: Int!
  """hasMore, and cursor = nextOffset as a string."""
  pageInfo: SemPageInfo!
  queryId: ID!
  """Rows stored for the run (after the cap)."""
  rowCount: Int!
  """Rows of this page, each an object keyed by column name."""
  rows: [JSON!]!
  runId: ID!
  """Rows the engine produced for the run (before the cap)."""
  totalRowCount: Int!
  """
  True when the stored rows are only the first rowCount of totalRowCount.
  """
  truncated: Boolean!
}

SemQueryRunResultColumn

"""One output column of a query run's result, in SELECT order."""
type SemQueryRunResultColumn {
  """
  Aggregation applied (SUM, AVG, MIN, MAX, COUNT, COUNT_DISTINCT), or null.
  """
  aggregation: String
  """Semantic entity the column is read from."""
  entity: String!
  """Logical field of the entity."""
  field: String!
  """
  The mask applied: NULL, REDACT or HASH (null when the column is not masked).
  """
  mask: String
  """
  True when a COLUMN access policy masked this column for the run's actor.
  """
  masked: Boolean!
  """Output alias: the key of this column in every row object."""
  name: String!
}

SemQueryRunStatus

enum SemQueryRunStatus {
  CANCELLED
  FAILED
  PLANNING
  QUEUED
  RUNNING
  SUCCEEDED
}

SemQueryStatus

enum SemQueryStatus {
  ARCHIVED
  DRAFT
  PUBLISHED
}

SemRecordConnectionInput

input SemRecordConnectionInput {
  dataSourceId: ID!
  health: SemConnectionHealth!
  latencyMs: Int
  message: String
}

SemRelationship

type SemRelationship @key(fields: "id") {
  createdAt: DateTime!
  description: String
  fromEntityId: ID!
  fromField: String!
  id: ID!
  kind: SemRelationshipKind!
  modelId: ID!
  name: String!
  toEntityId: ID!
  toField: String!
  updatedAt: DateTime!
  workspaceId: ID!
}

SemRelationshipKind

enum SemRelationshipKind {
  MANY_TO_MANY
  MANY_TO_ONE
  ONE_TO_MANY
  ONE_TO_ONE
}

SemRemoveWorkspaceDemoDataResult

type SemRemoveWorkspaceDemoDataResult {
  removedConnectors: Int!
  removedDataSources: Int!
  removedModels: Int!
  removedQueries: Int!
}

SemSeedWorkspaceDemoDataResult

"""
Identifiers of the demo records. `created` is false when the workspace already
held the demo data and the call returned the existing records unchanged.
"""
type SemSeedWorkspaceDemoDataResult {
  connectorId: ID!
  created: Boolean!
  dataSourceId: ID!
  entityIds: [ID!]!
  metricIds: [ID!]!
  modelId: ID!
  queryId: ID!
}

SemSemanticModel

type SemSemanticModel @key(fields: "id") {
  createdAt: DateTime!
  description: String
  entities: [SemEntity!]!
  id: ID!
  name: String!
  publishedAt: DateTime
  relationships: [SemRelationship!]!
  status: SemModelStatus!
  tags: [String!]!
  updatedAt: DateTime!
  version: Int!
  workspaceId: ID!
}

SemSemanticModelConnection

type SemSemanticModelConnection {
  items: [SemSemanticModel!]!
  pageInfo: SemPageInfo!
}

SemSqlCatalog

"""
The tables and columns a semantic model exposes to SQL (schema discovery for BI tools).
"""
type SemSqlCatalog {
  modelId: ID!
  modelName: String!
  tables: [SemSqlCatalogTable!]!
}

SemSqlCatalogColumn

type SemSqlCatalogColumn {
  """The metric's default aggregation (METRIC columns only)."""
  aggregation: String
  dataType: SemSqlDataType!
  description: String
  isPrimary: Boolean!
  kind: SemSqlColumnKind!
  name: String!
}

SemSqlCatalogTable

type SemSqlCatalogTable {
  columns: [SemSqlCatalogColumn!]!
  description: String
  kind: String!
  """Entity name: the table name to use in SQL."""
  name: String!
  primaryKey: String
}

SemSqlColumnKind

enum SemSqlColumnKind {
  DIMENSION
  METRIC
}

SemSqlDataType

"""
Data type of a SQL result or catalog column (the model's dimension data type).
"""
enum SemSqlDataType {
  BOOLEAN
  DATE
  DECIMAL
  GEO
  INTEGER
  JSON
  STRING
  TIMESTAMP
  """
  The column is not a registered dimension or metric, so its type is not known.
  """
  UNKNOWN
}

SemSqlResult

"""
The governed result of one SQL statement: rows exactly as the federated engine
produced them for the caller, with ROW access policies filtered and COLUMN
masks applied, then ordered, offset and capped.
"""
type SemSqlResult {
  columns: [SemSqlResultColumn!]!
  durationMs: Float!
  modelId: ID!
  """
  Execution plan, push-down and access-policy decisions for the statement.
  """
  planSummary: JSON!
  rowCount: Int!
  """Rows, each an object keyed by column name, in result order."""
  rows: [JSON!]!
  sourcesTouched: Int!
  """
  True when more rows matched than were returned (maxRows or the 5 MiB response cap).
  """
  truncated: Boolean!
}

SemSqlResultColumn

type SemSqlResultColumn {
  """
  Aggregation applied (SUM, AVG, MIN, MAX, COUNT, COUNT_DISTINCT), or null.
  """
  aggregation: String
  dataType: SemSqlDataType!
  """Semantic entity (table) the column is read from; '*' for COUNT(*)."""
  entity: String!
  """Logical field of the entity."""
  field: String!
  """
  The mask applied: NULL, REDACT or HASH (null when the column is not masked).
  """
  mask: String
  """True when a COLUMN access policy masked this column for the caller."""
  masked: Boolean!
  """Output column name: the key of this column in every row object."""
  name: String!
}

SemUpdateConnectorInput

input SemUpdateConnectorInput {
  capabilities: JSON
  description: String
  isActive: Boolean
  kind: SemConnectorKind
  name: String
}

SemUpdateDataSourceInput

input SemUpdateDataSourceInput {
  description: String
  endpoint: JSON
  name: String
  pushdownEnabled: Boolean
  """
  Reference to the credential this data source connects with; the credential itself is never stored or returned.
  One of: NAME or env://NAME (workspace-scoped environment variable), aws-sm://<name>[#<key>] (AWS Secrets Manager
  secret provisioned for this workspace, optionally one key of a JSON secret) or vault://<mount>/<path>#<key>
  (HashiCorp Vault KV v2 entry provisioned for this workspace). References always resolve inside the owning workspace.
  """
  secretRef: String
  tags: [String!]
}

SemUpdateEntityInput

input SemUpdateEntityInput {
  dataSourceId: ID
  description: String
  kind: SemEntityKind
  name: String
  physicalName: String
  primaryKey: String
  sqlDefinition: String
}

SemUpdateModelInput

input SemUpdateModelInput {
  description: String
  name: String
  tags: [String!]
}

SemUpdateNlSettingsInput

input SemUpdateNlSettingsInput {
  """
  Required when llmAssistEnabled is true: an OpenAI or Anthropic connection of this workspace.
  """
  aiConnectionId: ID
  """
  Optional provider model name, for example gpt-4o-mini or claude-opus-5-5.
  """
  aiModel: String
  llmAssistEnabled: Boolean!
}

SemUpdateQueryInput

input SemUpdateQueryInput {
  cacheTtlSeconds: Int
  cacheable: Boolean
  description: String
  modelId: ID
  name: String
  parameters: JSON
  queryText: String
  tags: [String!]
}