Searching the semantic layer¶
Studio has a search palette that finds anything in your Workspace's semantic layer: models, metrics, glossary terms, and the dimensions, measures and filters on your models.
Availability
- Who can do this: members with the Edit capability in the active Workspace.
- Deployment: Actian SaaS and self-managed deployments. Search by meaning needs an Embedding endpoint; without one, search matches keywords only. See Search by meaning or by name.
Open the search palette¶
On any Studio page, press Cmd+K (macOS) or Ctrl+K (Windows and Linux). There is no search button: the keyboard shortcut is the only way to open the palette.
To close it, press Esc, press the shortcut again, or click outside the palette.
The palette is available in Studio only. Explorer has no Cmd+K search.
Search¶
- Open the palette and start typing in Search models, metrics, glossary, fields….
- Search runs shortly after you stop typing and shows up to 10 of the best matches. Often you'll see fewer, because only results that are a good enough match are shown.
- Use the Up and Down arrow keys to move through the results. The highlight moves through all groups in the order shown.
- Press Enter, or click a result, to open it. The palette closes.
Before you type, the palette shows "Type to search the semantic layer by meaning or name."
What's searched¶
Search covers the semantic layer of the Workspace you're in. Deleted entities are not included.
Results are grouped. A group appears only when it has matches.
| Group | Contains | Opening a result |
|---|---|---|
| Models | Models | Opens the model |
| Metrics | Metrics | Opens the metric |
| Glossary | Glossary terms | Opens the term |
| Fields | Dimensions, measures and filters | Opens the parent model's page |
Each result shows its name and type. Field results also show their parent model, for example "Dimension · Orders".
Search by meaning or by name¶
Search works in one of two ways. The palette doesn't show which one is in use.
Search by meaning and by name (hybrid). When an Embedding endpoint is available, search combines matching by meaning with fuzzy text matching. Results can match related wording, not just the exact words you type, and near-misspellings still match.
Keyword search (lexical). Without a working Embedding endpoint, search uses fuzzy text matching only. This happens when:
- No Embedding endpoint is configured for your deployment or organization.
- The Embedding endpoint is failing.
- Your organization has just added or removed its own Embedding endpoint, while the semantic layer is re-indexed.
In both modes, text matching looks at more than names:
| Entity | Text that is matched |
|---|---|
| Models and metrics | Name, description and guidance |
| Glossary terms | Name, definition and synonyms |
| Dimensions, measures and filters | Name, description and parent model name |
So a clear description or a good set of synonyms makes an entity easier to find.
Add an Embedding endpoint for your organization¶
An organization can use its own OpenAI-compatible Embedding endpoint. This works on Actian SaaS and on self-managed deployments, and it replaces the deployment's embeddings for your organization.
Availability
- Who can do this: members with the Manage inference capability for the organization.
- Plan: included only in plans that include customer-hosted inference. Otherwise the Settings page shows "Your plan doesn't include customer-hosted inference, so your organization uses the deployment's default." and your organization uses the deployment's embeddings.
- In Studio, go to Settings → Inference.
- Under Search, click Add Embedding endpoint and enter the endpoint details.
- Click Test to check the endpoint and read the model's dimensions.
- Click Save. Your semantic layer is re-indexed through the endpoint, and search is keyword-only until that finishes.
Your semantic layer text (the fields in the table above) and your search queries are sent to this endpoint to be embedded, so use an endpoint your organization trusts.
If no endpoint is configured, the Search section reads "Search matches keywords only (lexical) until an Embedding endpoint is added."
If you remove your organization's endpoint, your organization returns to the deployment's embeddings and the semantic layer is re-indexed. Search is keyword-only until that finishes, or for good if the deployment has no embeddings.
Self-managed deployments
On self-managed deployments, embeddings are optional. If your operator hasn't configured an embedding model and your organization hasn't added its own Embedding endpoint, search is keyword-only. Air-gapped deployments don't require an Embedding endpoint.
Search in Steward and the AI Analyst¶
The same search powers other parts of the product:
- Steward @mentions. In the Steward composer, type @ to mention a model, metric, glossary term or field. The suggestions come from this search.
- AI Analysts and Steward. When they look for relevant parts of the semantic layer, they use the same search. AI Analysts only find items that their own access settings allow. Search by meaning can help them match related wording.
See Using Steward.
Troubleshooting¶
Nothing happens when I press Cmd+K or Ctrl+K. The palette works only on Studio pages. Make sure you're in Studio and not in Explorer.
"Search is unavailable right now. Try again in a moment." The search request failed. Wait a moment and try again. If you don't have the Edit capability in the Workspace, you can't search the semantic layer; ask a Workspace member who can manage members to grant it (see Workspaces).
"No matching entities found." Try a different word, a synonym or part of the name. If your organization has no Embedding endpoint, search matches text only, so try words that appear in the entity's name or description.
Results look keyword-based even though we added an Embedding endpoint. After you add or remove an endpoint, the semantic layer is re-indexed. Search is keyword-only until the re-index finishes.