Skip to Content

Semantic Layer APIs

Create a semantic layer

Describe a datamart's tables and columns for the first time.

POST
/api/v2/data-app/datamarts/semantic-layer

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.

Authorization

ServiceToken
headerAuthorizationBearer <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.

datamartNamestringrequired

The datamart.

tablesobject[]

Send this or the other one of the pair. Text per table.

6 fields in tables
namestringrequired

A table of the datamart.

descriptionstring | null

Limit: 500 characters. What the table holds.

Max length: 500
synonymsstring[]

Limit: 10 items, 100 characters each, no duplicates. Other words for the table.

Max items: 10
miscellaneousInfostring | null

Limit: 1,000 characters. Other notes.

Max length: 1000
columnsobject[]

Text per column.

8 fields in columns
namestringrequired

A column of that table.

descriptionstring | null

Limit: 500 characters. What the column holds.

Max length: 500
synonymsstring[]

Limit: 10 items, 100 characters each, no duplicates. Other words for the column.

Max items: 10
miscellaneousInfostring | null

Limit: 1,000 characters. Other notes.

Max length: 1000

Limit: See below. The kind of value.

One of: StringLong StringString (Custom)ENUMMapperRangeExpressionIdentifierNumberJSON

Limit: 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.

schemaNamestring | null

Accepted and ignored. Tables are matched by name.

feedbackstring | null

Send this or the other one of the pair. Limit: 2,000 characters. A note on the whole datamart.

Max length: 2000

Column types

columnTypeColumn data typecolumnTypeConfig
String, Long String, String (Custom), ENUM, MapperText (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
NumberNumeric (int, bigint, decimal, numeric, float, double and the like)None
RangeNumeric{ "lowerLimit": 0, "upperLimit": 100 }
JSONjson or jsonbA sample JSON as a string
ExpressionAnyA string template
IdentifierAnyNone

Response

{ "id": "Sales" }

id is the datamart name. Databrain also updates the datamart's completion score. See Get a semantic layer.

Errors

Statuserror.codeWhy
400INVALID_REQUEST_BODYA field is missing, unknown or too long, or neither tables nor feedback was sent
400INVALID_DATAMARTNo datamart has this name
400INVALID_TABLETable '<table>' not found in datamart '<datamart>'
400INVALID_COLUMNColumn '<column>' not found in table '<table>'
400INVALID_COLUMN_TYPEThe column type does not fit the column's data type
400INVALID_COLUMN_TYPE_CONFIGcolumnTypeConfig has the wrong shape, or columnType is missing
400DUPLICATE_SYNONYMThe same synonym is in a list twice, in any letter case
403AUTHENTICATION_ERRORYou used a data app API token
409SEMANTIC_LAYER_ALREADY_EXISTSThe datamart already has a semantic layer. Use PUT
409LAYER_MANAGED_BY_V2The 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.

Example Request
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."}'
Example Response
{  "id": "Sales"}