Skip to Content

Datamart APIs

Update a datamart

Replace a datamart's tables or joins, or change its tenancy.

PUT
/api/v2/data-app/datamarts
curl --request PUT https://api.usedatabrain.com/api/v2/data-app/datamarts \  --header "Authorization: Bearer $DATABRAIN_SERVICE_TOKEN" \  --header "Content-Type: application/json" \  --data '{    "datamartName": "Sales",    "tenancySettings": { "tenancyLevel": "DATABASE", "primaryDatabase": "tenant_default" }  }'

Auth

A service token. See Authentication.

Authorization

ApiToken
headerAuthorizationBearer <token>

A service token or a data app API token.

Body

The fields have the same shape and values as Create a datamart.

datamartNamestringrequired

Picks the datamart. You cannot rename it.

tableListobject[]

Replaces all tables and columns. Leave it out to keep them. [] removes them all.

7 fields in tableList
namestringrequired

Table name, as in the synced schema.

schemaNamestringrequired

Schema of the table. Can be database.schema

columnsobject[]required

At least one column.

11 fields in columns
namestringrequired

Column name, as in the schema. Any name if isCustomColumn is true

aliasstring

Alias.

labelstring

Display name.

isHideboolean

Hide the column. Default false

A calculated column. Default false

sqlstring

Required with isCustomColumn. SQL expression of the calculated column.

The expression is already an aggregate.

Convert this date column to the guest token's timezone. Default false

allowAggregateboolean | null

Allow a default aggregation. A JSON boolean, not a string.

defaultAggregationstring | null

ALL, AVG, SUM, COUNT, COUNT_DISTINCT, MAX, MIN, MEDIAN, PERCENTILE_CONT or PERCENTILE_DISC

defaultSortstring | null

ASC or DESC

The table's tenant column, for TABLE tenancy.

labelstring

Display name.

isHideboolean

Hide the table from metric builders. Default false

wildcardstring

Stored with the table.

A non-empty list replaces all joins. Leave it out or send [] to keep them.

7 fields in relationships
relationshipNamestringrequired

Name of the join.

parentTableNamestringrequired

One side of the join.

parentColumnNamestringrequired

One side of the join.

childTableNamestringrequired

The other side.

childColumnNamestringrequired

The other side.

cardinalitystring | null

OneToOne, OneToMany, ManyToOne or ManyToMany

joinstring | null

INNER JOIN, LEFT JOIN, RIGHT JOIN or FULL JOIN

Changes the fields you send.

7 fields in tenancySettings

TABLE (a tenant column), DATABASE (a schema or database per tenant) or MULTI_DATABASE

Required for TABLE. STRING or NUMBER

Required for TABLE. The table that lists your tenants.

tableNamestring

Required for TABLE. The table that lists your tenants.

Required for TABLE. Column with the tenant name.

Required for TABLE. Column with the tenant id, the value you send as clientId

Default database for DATABASE and MULTI_DATABASE

On a datamart without a semantic model, sending tableList deletes the semantic layer text (descriptions, synonyms, column types) of every table. Send it again with Update a semantic layer.

Tenancy rules:

  • A field you leave out, or send as "" or null, keeps its saved value.
  • With tenancyLevel TABLE, also send clientColumnType, schemaName, tableName, tableClientNameColumn and tablePrimaryKeyColumn.
  • primaryDatabase is kept only when this request sets tenancyLevel to DATABASE or MULTI_DATABASE. Otherwise it is cleared.

When a table loses its tenant column, Databrain keeps that column on the data apps and embeds that use it, and says so in warnings.

Response

{  "id": "Sales",  "warnings": [    "Kept the client column of 2 embed or data app setting(s) (orders): the datamart table has no client column, so it is their live client filter."  ]}

id is the datamart name. warnings is there only when it has items.

Errors

Statuserror.codeWhy
400INVALID_REQUEST_BODYA field is missing, unknown or wrong, or a table or column is not in the schema
400INVALID_DATAMARTNo datamart has this name
409LAYER_MANAGED_BY_V2The joins of this datamart belong to its semantic model. Edit them in the app
500INTERNAL_SERVER_ERRORThe datamart could not be updated

For errors that every endpoint returns, see Authentication.

Example Request
curl -X PUT 'https://api.usedatabrain.com/api/v2/data-app/datamarts' \  -H 'Content-Type: application/json' \  -d '{  "datamartName": "Sales",  "tenancySettings": {    "tenancyLevel": "DATABASE",    "primaryDatabase": "tenant_default"  }}'
Example Response
{  "id": "Sales",  "warnings": [    "Kept the client column of 2 embed or data app setting(s) (orders): the datamart table has no client column, so it is their live client filter."  ]}