Create TenantDatasetSource

LLM-friendly URL
POST
https://api.luzmo.com/0.1.0/tenantdatasetsource
API call form
Examples

A tenant dataset source links a tenant and a base dataset to a connection and a table ( source_sheet ) or SQL query ( source_query ). When an embed token of that tenant queries the base dataset, Luzmo queries the tenant's table or query instead of the base dataset's own source. Callers without a tenant keep querying the base dataset's source.

The tenant's table or query must contain every shared field of the base dataset: each column that has a source_name , is not a derived column, and is not assigned to a tenant. A shared field matches a column of the tenant's table or query when source_name , type and source_type are all equal. The tenant's table or query can contain additional columns: these are the tenant's own fields.

Tenant field discovery

  • When an embed token of the tenant retrieves the base dataset with a Column include, the response also contains the additional columns of the tenant's table or query. These are discovered fields: they are not saved yet. A where , limit or offset on the Column include leaves them out.

  • A discovered field has a deterministic id : the same tenant, dataset and source column always give the same id.

  • Search Column does not return a discovered field, and updating or deleting it returns 404 .

  • A discovered field is saved the first time the tenant uses it in a data query, or references it in the expression of a derived column or formula. Luzmo then saves it as a column of the base dataset, with the same id , assigned to the tenant. Referencing it in an expression requires use rights on the dataset through the token's rights .

  • A saved column behaves like any other tenant field. Changing it requires modify through the token's tenant_fields_rights (see Create Authorization ).

Queries on a tenant dataset source don't use the base dataset's acceleration . They always run on the tenant's table or query.

Only main-organization users can create, retrieve, update or delete tenant dataset sources. For other callers, such as embed tokens of a tenant, these requests fail with 403 .

Create a tenant dataset source. You need modify rights on the base dataset and Use rights on the connection. A tenant can have one tenant dataset source per dataset, and can use different connections for different datasets.

Creating a tenant dataset source does not create columns. Tenant fields are discovered when the tenant retrieves the dataset, and saved when the tenant uses them.

Luzmo validates the source against the connection before it saves it. Error messages call the tenant's table or query the "tenant source", and the base dataset the "logical dataset".

Status Message Cause
400Exactly one of source_sheet or source_query is required. Both or neither of source_sheet and source_query are set.
400<property> must be a UUID.tenant_id , securable_id or account_id is not a UUID.
403You need Modify rights on dataset <id> to manage its tenant dataset sources. No modify rights on the base dataset.
403You need Use rights on connection <id> to route a tenant to it. No Use rights on the connection.
404No tenant found with id <id>. The tenant doesn't exist in your organization.
409A tenant dataset source already exists for this tenant and dataset. The tenant already has a tenant dataset source for this dataset.
400<id> is a dashboard; tenant dataset sources apply to datasets.securable_id is a dashboard.
400Datasets on provider '<provider>' cannot have tenant dataset sources. The base dataset has no connection, or its connector doesn't support schema discovery.
400The logical dataset uses provider '<provider>'; the tenant connection uses '<provider>'. The connection uses a different provider than the base dataset's connection.
400The tenant source '<source_sheet>' could not be resolved on the connection. The table or query doesn't exist or fails on the connection.
502Could not reach the tenant source '<source_sheet>' (provider <provider>). Luzmo could not connect to the connection.
400Shared field '<name>' was not found in the tenant source. A shared field is missing from the tenant's table or query.
400Shared field '<name>' is <type> in the logical dataset but <type> in the tenant source. A shared field has a different type .
400Shared field '<name>' has source type '<type>' in the logical dataset but '<type>' in the tenant source. A shared field has a different source_type .
400The tenant source query returns more than one column named '<name>'. The SQL query returns duplicate column names. For a table: The tenant source has more than one column named '<name>'.
400The logical dataset has more than one shared column with source name '<name>' (<ids>). The base dataset has two shared columns with the same source_name .

For a SQL source, the messages that name '<source_sheet>' name 'the configured SQL source' instead.

Request parametersResponse schema
id UUID

The unique identifier of the entity

tenant_id UUID

ID of the tenant whose queries are routed. Immutable after creation.

securable_id UUID

ID of the base dataset. The dataset must be on a connection that supports schema discovery, such as a database connection or a plugin. Datasets without a connection (e.g. created with the data endpoint) and datasets on connectors with managed metadata (e.g. Google Drive, Google Analytics) cannot have tenant dataset sources. Immutable after creation.

account_id UUID

ID of the connection that holds the tenant's table or SQL query. The connection must use the same provider as the base dataset's connection (e.g. postgresql ), and you need Use rights on it. It can be the base dataset's own connection.

source_sheet STRING

Table that holds the tenant's data, in the same format as the source_sheet of the base dataset (e.g. <schema>.<table> ). Set exactly one of source_sheet and source_query ; an empty string counts as not set.

source_query STRING

SQL query that returns the tenant's data. Set exactly one of source_sheet and source_query ; an empty string counts as not set. The query must not return two columns with the same name.

acceleration_id UUID

Always null . It cannot be set through the API.

created_at DATETIME

RFC 3339 date time string indicating when the resource was created

updated_at DATETIME

RFC 3339 date time string indicating when the resource was last updated

Can be executed by:
Organization Member (main organization)
Dataset Modifier
Connection User
Can be associated to:
Tenant
Securable
Account
Did this page help you?
Yes No
Language
Shell
Node
Java
.NET
Python
PHP
Install
npm install @luzmo/nodejs-sdk
Example Request 
import Luzmo from '@luzmo/nodejs-sdk';
const client = new Luzmo({
  api_key: '<your Luzmo API key>',
  api_token: '<your Luzmo API token>',
  host: 'https://api.luzmo.com'
});


const response = await client.create('tenantdatasetsource',
  {
    tenant_id: "<tenant_id>",
    securable_id: "<dataset_id>",
    account_id: "<connection_id>",
    source_sheet: "< schema >.< tenant table >"
  }
);
You are not authenticated.
Log in to try
Example Response
200
400
500
{
  "tenant_id": "508eb8ae-24f6-4f6e-a0cc-c050258af89e",
  "securable_id": "f2f9c24b-bb17-4886-ba77-c5ee9dbc14e7",
  "account_id": "99dc1808-bfd9-49f7-b448-e611e6e10a13",
  "source_sheet": "public.burritos_suborg",
  "id": "deea1671-0a97-4d3f-935a-1cbe7f1921a8",
  "source_query": null,
  "updated_at": "2026-09-29T11:08:09.661Z",
  "created_at": "2026-09-29T11:08:09.661Z",
  "acceleration_id": null
}