Semantic search (API)

Semantic search ranks your workspace’s assets against what you type. It answers from one of two lanes:

By meaning (vector), when the server has an embeddings service turned on: a search for “customer churn” surfaces a dashboard called Retention overview even though neither word appears in its name. Reading the meaning of each search, and keeping the index up to date, are AI steps that use the workspace’s AI credits.
By spelling and your glossary (lexical) otherwise, and always for an API key. Names are compared with your query by their letters, so a typo or part of a word still finds them; descriptions count half as much. A query that matches a glossary term or one of its synonyms also searches for the term and its synonyms, and finds the metrics and fields linked to the term.

Search from the app

Press Ctrl+K (Cmd+K on a Mac), or click the search field in the top bar, to open the command palette from any page. It does four things:

Finds your work. Type at least two characters. Dashboards, reports, stories, data models and data sources whose names match appear under Search Results, and Catalog lists what semantic search finds: metrics, model fields and saved queries, and dashboards not already listed, each with its kind (Metric, Field, Query or Dashboard). With nothing typed, it offers shortcuts and questions to ask about the page you are on, with Build a dashboard with AI… and Open AI Chat. Inside an editor, that editor’s own commands come first, and the box reads Search commands or ask AI….
Runs shortcuts. New dashboard, New story, Open SQL editor, Connect Data Source and Open Recovery Center are offered when your role allows them.
Filters by kind. Use the Dashboards, Stories and Queries buttons (or All) to narrow the list, move with the arrow keys, press Enter to open the highlighted item and Esc to close.
Asks AI. Type a question and choose Ask AI — it is answered in the AI chat panel, about the page you are on. Ctrl+Enter (⌘↵ on a Mac) opens it on the AI page instead. A question lists Ask AI first; a name lists your matching work first, with Ask AI after it once the search has answered.

Press Ctrl+K (Cmd+K on a Mac), or choose Search workspace at the top of any page. The palette opens with your recent items and shortcuts to pages.
Type two or more characters. Matching dashboards, metrics, fields and queries appear in groups as you type.
Use the arrow keys or the mouse to choose a result, then press Enter. The page opens.

What it searches

Four kinds of asset, all scoped to the caller’s workspace:

`kind`	Covers
`dashboard`	dashboards
`metric`	governed metrics
`model_field`	fields across your data models
`saved_query`	the saved query library

Searching

POST /api/search/semantic, authenticated like any other REST call. No extra scope and no product license are involved — any authenticated caller with a workspace can search it, though saved queries come back only for a caller whose role may view the SQL editor. An API key is always answered by the lexical lane: embedding the query is an AI step, and API keys can’t use AI.

curl -X POST https://<your-datasquares-host>/api/search/semantic \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"q": "revenue by region", "kinds": ["dashboard", "metric"], "limit": 5}'

Field	Type	Notes
`q`	string	required — the natural-language query, up to 1,000 characters
`kinds`	`string[]`	optional — any of the four kinds above; omit to search all four
`limit`	integer	optional — default `20`, maximum `100`

Hits come back ranked by score (higher is closer), and mode says which lane answered:

{
  "semantic": true,
  "reason": null,
  "mode": "lexical",
  "hits": [
    {
      "kind": "dashboard",
      "id": "8f3c…",
      "name": "Regional revenue",
      "description": "Bookings and ARR by sales region",
      "score": 0.82,
      "updatedAt": "2026-07-01T09:12:44.000Z",
      "modelId": null,
      "tableId": null
    }
  ]
}

modelId and tableId are filled in for model_field hits only, so you can jump straight to the field’s table.

A model_field hit also says whether the field carries a sensitivity label: labelled is true, and the field is found by its name like any other, since names are not values. Its description reaches someone who can’t see labelled values in clear (anyone but a company admin, and every API key) only when it holds nothing that looks like a value, nothing personal or secret and no instruction: the rule a note passes. Otherwise the hit’s description is null, and the description isn’t searched either, so a hit never answers for words you can’t see.

When it can’t answer

Semantic search degrades honestly rather than failing. When the meaning lane can’t answer (the server has no embeddings service, search by meaning is turned off under Administration → AI, the AI credits or budget are used up, the caller is an API key, the query couldn’t be embedded, or nothing in the workspace is indexed yet), the lexical lane answers instead, with mode: "lexical". Only when that lane fails too do you get a 200 with semantic: false, reason: "lexical_failed" and no hits, so your caller can fall back to its own name matching. It never raises an error for these cases. Read mode before you take the ranking for one by meaning.

Reindexing

The meaning lane’s index maintains itself in the background as assets change, so you normally don’t touch it; embedding the changed assets uses the workspace’s AI credits. A company admin can force a rebuild of their workspace’s index:

curl -X POST https://<your-datasquares-host>/api/search/semantic/reindex \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"force": true}'

It reports what it did — scanned, embedded, purged — plus a reason when it couldn’t embed: no_provider when the server has no embeddings service, embed_failed when embedding failed. Anyone else, API keys included, gets a 403.

AI chat — in-product and conversational.
Search API reference — the generated endpoint reference.