Semantic Layer APIs
Create a semantic layer
Describe a datamart's tables and columns for the first time.
Use it once per datamart. To change it later, use Update a semantic layer.
curl --request POST https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer \ --header "Authorization: Bearer $DATABRAIN_SERVICE_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "datamartName": "Sales", "tables": [ { "name": "orders", "description": "One row per order.", "synonyms": ["purchases", "sales"], "columns": [ { "name": "amount", "description": "Order total in USD.", "columnType": "Number" }, { "name": "status", "columnType": "ENUM", "columnTypeConfig": { "paid": "Payment received", "refunded": "Money returned" } }, { "name": "id", "columnType": "Identifier", "isIdentifier": true } ] } ], "feedback": "Revenue means the sum of paid orders." }'Auth
A service token only. See Authentication.
ServiceTokenAuthorizationBearer <token>A service token. A data app API token is refused.
Body
Send datamartName and at least one of tables or feedback. Unknown fields are refused.
The datamart.
Send this or the other one of the pair. Text per table.
6 fields in tables
A table of the datamart.
Limit: 10 items, 100 characters each, no duplicates. Other words for the table.
10Text per column.
8 fields in columns
A column of that table.
Limit: 10 items, 100 characters each, no duplicates. Other words for the column.
10Limit: See below. The kind of value.
StringLong StringString (Custom)ENUMMapperRangeExpressionIdentifierNumberJSONLimit: See below. Values for the column type. Send columnType with it.
The column identifies a row.
Do not give this column's ENUM values to Bryn.
Accepted and ignored. Tables are matched by name.
Send this or the other one of the pair. Limit: 2,000 characters. A note on the whole datamart.
2000Column types
columnType | Column data type | columnTypeConfig |
|---|---|---|
String, Long String, String (Custom), ENUM, Mapper | Text (varchar, text, char, string, nvarchar and the like) | String, String (Custom), ENUM, Mapper: an object of value to description, for example { "paid": "Payment received" }. Long String: none |
Number | Numeric (int, bigint, decimal, numeric, float, double and the like) | None |
Range | Numeric | { "lowerLimit": 0, "upperLimit": 100 } |
JSON | json or jsonb | A sample JSON as a string |
Expression | Any | A string template |
Identifier | Any | None |
Response
{ "id": "Sales" }id is the datamart name. Databrain also updates the datamart's completion score. See Get a semantic layer.
Errors
| Status | error.code | Why |
|---|---|---|
| 400 | INVALID_REQUEST_BODY | A field is missing, unknown or too long, or neither tables nor feedback was sent |
| 400 | INVALID_DATAMART | No datamart has this name |
| 400 | INVALID_TABLE | Table '<table>' not found in datamart '<datamart>' |
| 400 | INVALID_COLUMN | Column '<column>' not found in table '<table>' |
| 400 | INVALID_COLUMN_TYPE | The column type does not fit the column's data type |
| 400 | INVALID_COLUMN_TYPE_CONFIG | columnTypeConfig has the wrong shape, or columnType is missing |
| 400 | DUPLICATE_SYNONYM | The same synonym is in a list twice, in any letter case |
| 403 | AUTHENTICATION_ERROR | You used a data app API token |
| 409 | SEMANTIC_LAYER_ALREADY_EXISTS | The datamart already has a semantic layer. Use PUT |
| 409 | LAYER_MANAGED_BY_V2 | The datamart belongs to a semantic model. Edit it in the app |
Tables and columns are saved one at a time. If a call fails part way, read the layer with GET before you try again.
For errors that every endpoint returns, see Authentication.
curl -X POST 'https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer' \ -H 'Content-Type: application/json' \ -d '{ "datamartName": "Sales", "tables": [ { "name": "orders", "description": "One row per order.", "synonyms": [ "purchases", "sales" ], "columns": [ { "name": "amount", "description": "Order total in USD.", "columnType": "Number" }, { "name": "status", "columnType": "ENUM", "columnTypeConfig": { "paid": "Payment received", "refunded": "Money returned" } }, { "name": "id", "columnType": "Identifier", "isIdentifier": true } ] } ], "feedback": "Revenue means the sum of paid orders."}'{ "id": "Sales"}