SDK Reference

This is a compact reference for the public Data App SDK surface.

Imports

import {
  SemaphorDataAppProvider,
  defineSemaphorDataApp,
  defineSemaphorInput,
  semaphor,
  useClearInvalidSemaphorInputValue,
  useSemaphorInput,
  useSemaphorInputs,
  useSemaphorQuery,
} from 'react-semaphor/data-app-sdk';

Provider

<SemaphorDataAppProvider token={token} apiBaseUrl={apiBaseUrl}>
  <App />
</SemaphorDataAppProvider>

Props:

Prop	Required	Meaning
`token`	Local development	Scoped Semaphor access token.
`apiBaseUrl`	Optional	API base URL for local or self-hosted environments.
`executor`	Optional	Custom query executor, usually for tests.

Source Builders

semaphor.source.semantic({
  domainId: 'commerce',
  datasetName: 'fact_orders',
  datasetId: 'ds_orders',
  connectionId: 'conn_123',
  label: 'Orders',
});

semaphor.source.sql({
  connectionId: 'conn_123',
  dialect: 'postgres',
  label: 'Analytics warehouse',
});

For semantic sources, provide domainId and datasetName; include datasetId when available to strengthen identity. connectionId is execution metadata, not the semantic identity.

Field Builders

semaphor.field.measure('revenue', { source: orders, aggregate: 'SUM' });
semaphor.field.dimension('campaign_name', { source: campaign });
semaphor.field.date('order_date', { source: orders });
semaphor.field.id('campaign_id', { source: campaign });

Query Builders

semaphor.metric({
  source,
  measures,
  primaryMeasure,
});

semaphor.records({
  source,
  fields,
  dateField,
  orderBy,
  limit,
  pagination,
});

semaphor.matrix({
  source,
  rows,
  columns,
  values,
  totals,
});

semaphor.analysis({
  source,
  measures,
  primaryMeasure,
  dimensions,
  analysis,
});

semaphor.inputOptions({
  inputId,
  source,
  labelField,
  valueField,
  searchField,
  population,
  dependencies,
  limit,
});

semaphor.sql({
  source,
  sql,
  rationale,
  limit,
  pagination,
});

Input Builders

semaphor.filter({
  id: 'campaign',
  label: 'Campaign',
  field: campaignId,
  operator: 'in',
  multi: true,
});

semaphor.control({
  id: 'grain',
  label: 'Grain',
  role: 'grain',
  defaultValue: 'month',
});

With the current React SDK, apps usually call useSemaphorInput directly:

const campaignInput = useSemaphorInput({
  id: 'campaign',
  label: 'Campaign',
  kind: 'filter',
  field: campaignId,
  operator: 'in',
  multi: true,
});

Hooks

const input = useSemaphorInput(spec);
const inputs = useSemaphorInputs([campaignSpec, dateSpec]);
const result = useSemaphorQuery(query, { inputs: [input] });
useClearInvalidSemaphorInputValue(input, optionsResult);

useSemaphorQuery is overloaded by query kind, so the result shape follows the builder you pass.

Common Result Fields

All results:

result.status;
result.isLoading;
result.error;
result.executionResult;

Metric:

result.value;
result.measures;
result.delta;
result.deltaPercent;

Records and SQL:

result.records;
result.columns;
result.rowCount;
result.pagination;

Input options:

result.options;

Matrix:

result.matrixResult;
result.grid;

Analysis:

result.answerSummary;
result.resultSets?.records?.records;
result.resultSets?.changes?.records;
result.resultSets?.drivers?.records;
result.analysisWarnings;

executionResult is the authoritative governed result contract. Top-level analysis fields such as records, drivers, changes, or fieldsUsed are convenience projections for display. In particular, top-level fieldsUsed is compact display metadata; full derived-field lineage belongs in executionResult.fieldsUsed.

Option Population

population: {
  kind: 'related_population',
  baseSource: inventory,
}

Use related_population when the option source should be limited by a related fact or bridge population.

Option Dependencies

Normal cascading filters can omit dependencies.

const stateOptions = semaphor.inputOptions({
  inputId: 'state',
  source: geo,
  labelField: stateName,
  valueField: stateId,
});

The default is auto: compatible active inputs can narrow the option list, except the input's own value.

Use explicit dependencies only when needed:

dependencies: {
  mode: 'explicit',
  includeInputIds: ['region'],
}

Relationship Hint

Use only when Semaphor reports an ambiguous relationship and the user or planner selects one modeled path.

relationshipHint: {
  relationshipIds: ['rel_orders_buyer_customer'],
}

Do not use free-form role aliases as hints.

SDK Reference

On this page