How to Query, Script, and Model MetaKarta in Code
The Developer Guide is for data engineers and platform developers who automate MetaKarta or build on it. It covers Metadata Query Language (MQL), which drives Search and Worksheets in the UI as well as the REST API; the REST API itself, including authentication, responses, and object ID formats; and Semantic Hub Language (SHL), the YAML-based language semantic models are defined in. After reading it, you can write MQL queries, script REST calls with an API key, and author SHL files that pass validation.
Note
Some of the features detailed in this document may not apply and/or be available for the particular edition/version you are using.
Get started
Frequently asked questions
What does MQL query syntax look like, and where is MQL used?
MQL runs behind Search and Worksheets in the UI and behind the REST API. A query has a SELECT list and a FROM clause, plus optional CONTEXT, WHERE, and ORDER BY clauses. MQL is case-insensitive except for attribute names in SELECT, WHERE, and ORDER BY, and certain filter values in WHERE.
See MQL general rules.
How do I authenticate to the MetaKarta REST API?
Most methods take an api-key header. Get a key from POST /auth/loginPlainText, which returns the key as a string, or from the result property of POST /auth/login.
A key stops working after /auth/logout or when the login times out. If you're upgrading older scripts, the header was renamed from api_key to api-key in 11.1.0.
Where is the REST API reference documentation?
Endpoints are documented in Swagger. A read-only copy is published at docs.metakarta.com/rest-api/, and a live copy runs inside the MetaKarta application server once an administrator enables it (it's off by default for security). The Deployment Guide's REST API Documentation Setup page covers enabling it.
See the REST API overview.
What is Semantic Hub Language (SHL)?
SHL is the YAML-based language you define semantic models in. Definitions are Git-integrated, composable (objects defined separately work together), and deployable across warehouses and BI tools. The specification covers catalogs, connections, models, composite models, semantic tables, glossaries, and row security.
See the SHL Overview.
What are the validation requirements for an SHL file?
A catalog needs a name, a default connection, and at least one connection, model, and table, all uniquely named. A model needs a fact that points to an available semantic table, and its visible columns need unique names. For Oracle Analytic Views, each attribute dimension needs a level; if a table defines none, the export bridge generates one.
See SHL validation rules.
What are the known limitations of MQL?
Two are documented. Some system attributes can't be combined with OR in a WHERE clause, and the Conditional Labels attribute can't be used as a Parent or Children property in a WHERE clause (you can still select it). The page points to the full list of affected system attribute filters.
See MQL limitations.
Which REST API changes affect existing scripts?
The REST API and MQL each keep release change pages, currently for MIMM 11.1 and 11.0. Check them before upgrading scripts or integrations, since some changes (such as the api-key header rename) affect existing calls. Some features in these notes may not apply to your edition.
Related documentation
Return to the MetaKarta documentation home. For the Search and Worksheets features MQL drives, see the User Guide; for API and MQL changes by version, see Releases & Roadmap.