Overview

Data Apps let you build custom analytics experiences on top of Semaphor's governed semantic layer. You can build dashboards, workflow tools, operational tables, and embedded analytics screens while Semaphor handles authentication, server-side query execution, semantic relationships, and result metadata.

Use Data Apps when you want more control than a standard dashboard card but still want the safety of governed analytics.

What You Build

A Data App is an application built with a Semaphor client SDK. The examples in these docs use the current React SDK, but the concepts are framework-agnostic. Your app defines:

• sources: the semantic datasets you want to query, such as fact_orders or dim_campaign.
• fields: measures, dimensions, dates, and ids from those sources.
• queries: KPI, records, matrix, analysis, input-options, or SQL fallback specs.
• inputs: filters and controls that users can change.
• views: UI components that render the query results.

Semaphor executes the query server-side and returns typed results to your app.

import {
  SemaphorDataAppProvider,
  semaphor,
  useSemaphorQuery,
} from 'react-semaphor/data-app-sdk';

const orders = semaphor.source.semantic({
  domainId: 'commerce',
  datasetName: 'fact_orders',
});

const revenue = semaphor.field.measure('revenue', {
  source: orders,
  aggregate: 'SUM',
});

function RevenueKpi() {
  const result = useSemaphorQuery(
    semaphor.metric({
      id: 'revenue_kpi',
      label: 'Revenue',
      source: orders,
      measures: [revenue],
      primaryMeasure: revenue,
    }),
  );

  if (result.isLoading) return <div>Loading revenue...</div>;
  if (result.error) return <div>{result.error.message}</div>;

  return <strong>{result.value}</strong>;
}

export function App({ token }: { token: string }) {
  return (
    <SemaphorDataAppProvider token={token}>
      <RevenueKpi />
    </SemaphorDataAppProvider>
  );
}

Why This Is Different From Client-Side Analytics

Data Apps are not a "fetch every row and filter in the browser" pattern. Your app declares intent, and Semaphor executes that intent through governed server-side analytics.

This matters because production dashboards often need:

• relationship-aware filters, such as a Campaign dropdown filtering an Orders fact table;
• joined labels, such as revenue by campaign name instead of campaign id;
• cascading filters, such as Region narrowing State;
• server-side pagination and sorting for large tables;
• diagnostics when a relationship is missing, ambiguous, or unsafe.

Start Here

Core Mental Model

Imagine a commerce company with this semantic model:

fact_orders
  order_id
  order_date
  campaign_id
  store_id
  revenue

dim_campaign
  campaign_id
  campaign_name
  channel

dim_store
  store_id
  store_name
  state_id

dim_geo
  region_id
  region_name
  state_id
  state_name

fact_orders stores revenue and ids. dim_campaign, dim_store, and dim_geo store human-readable labels. Semaphor's semantic model defines relationships such as:

fact_orders.campaign_id -> dim_campaign.campaign_id
fact_orders.store_id -> dim_store.store_id
dim_store.state_id -> dim_geo.state_id

With those relationships, a Data App can:

• show revenue from fact_orders;
• display campaign names from dim_campaign;
• filter revenue by campaign name;
• cascade Region and State options from dim_geo;
• apply Region and State filters to fact_orders through dim_store.

Your app authors the source and field refs. Semaphor proves and executes the relationships.

Recommended Reading Order

1. Quickstart
2. Components
3. SDK Concepts
4. Queries
5. Filters And Inputs
6. Relationship-Aware Filters And Joins
7. Tables
8. Validation And Debugging