--- title: "How do I create a relational dataset definition?" slug: "how-do-i-create-a-relational-dataset-definition" updated: 2026-04-08T14:25:44Z published: 2026-04-08T14:25:44Z canonical: "support.lusid.com/how-do-i-create-a-relational-dataset-definition" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.lusid.com/llms.txt > Use this file to discover all available pages before exploring further. # How do I create a relational dataset definition? You must create a relational dataset definition (RDD) to define the schema of a dataset before you can [add records to it](/v1/docs/how-do-i-add-records-to-a-custom-dataset). A dataset is equivalent to a table in a relational database. It can have a finite set of columns, a (nominally) infinite set of rows, and a nominated subset of columns that form (part of) the primary key. [Anatomy of a dataset](/v1/docs/anatomy-of-a-dataset). ## Methods LUSID APILUSID web appLuminesce Call the [CreateRelationalDatasetDefinition](https://www.lusid.com/docs/api/lusid/endpoints/relational-dataset-definition/CreateRelationalDatasetDefinition/) API, for example: ```json curl -X POST 'https://.lusid.com/api/api/relationaldatasetdefinitions'  -H 'Content-Type: application/json-patch+json'  -H 'Authorization: Bearer '  -d '{  "id": {    "scope": "MyDatasets",    "code": "Addresses"  },  "displayName": "Address custom dataset",  "description": "A custom dataset modelling addresses for people and organisations",  "applicableEntityTypes": ["Person","LegalEntity"],  "fieldSchema": [    {      "category": "SeriesIdentifier",      "fieldName": "AddressType",      "displayName": "Address type",      "description": "Whether a correspondence or a registered address",      "dataTypeId": {"scope": "MyCustomDataTypes", "code": "AddressType"},      "required": true,    },    {      "category": "Value",      "fieldName": "Street",      "displayName": "Street",      "description": "Building number/name and street",      "dataTypeId": {"scope": "system","code": "string"},      "required": true,    },    {      "category": "Value",      "fieldName": "City",      "displayName": "Town or city",      "dataTypeId": {"scope": "system","code": "string"},      "required": true,    },    {      "category": "Metadata"      "fieldName": "Email",      "displayName": "Contact email",      "description": "Email address for primary contact",      "dataTypeId": {"scope": "system","code": "string"}    }  ] }' ``` ***Coming soon*** Write a Luminesce SQL query using the [Lusid.RelationalDataset.Definition.Writer](/v1/docs/lusidrelationaldatasetdefinitionwriter) provider and execute it using a tool such as the LUSID web app, for example: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-NG7G3PZP.png) ## Request fields This section supplements the [API documentation](https://www.lusid.com/docs/api/lusid/endpoints/relational-dataset-definition/CreateRelationalDatasetDefinition) and on-screen help text in the LUSID web app. A RDD: - Must have a `scope` and a `code` that together uniquely identify it. - Must have a `displayName` and can have a `description`. - Must reference at least one of the `applicableEntityTypes` in the following list: `Portfolio`, `Instrument`, `Transaction`, `Person`, `LegalEntity`, `InvestorRecord`, `InvestmentAccount`, `Holding`, `SettlementInstruction`. Note each record in the dataset can be associated with one, some, or all entities of a particular type. - Must have a `fieldSchema` containing at least one mandatory `Value` field (see below). A `fieldSchema`: - Can have one or more `SeriesIdentifier` fields. It may have none. Note that each forms part of the primary key, in conjunction with information about associated entities. While a `SeriesIdentifier` can be optional, note that if a user omits a value then part of the key will be missing for that record. - Must have at least one mandatory `Value` field. The remainder can be optional. - Can have one or more `Metadata` fields, mandatory or optional. The maximum number of fields is 100, of which no more than 50 can be `SeriesIdentifier` fields. Each: - Must have a unique `fieldName` (no spaces), and can have a verbose `displayName` and `description`. - Must have a category of either `SeriesIdentifier`, `Value` or `Metadata`. - Can set `required` to `true`. The default is `false`. At a minimum, one `Value` field must be `true`. - Must reference the `dataTypeId` of a [built-in or custom data type](/v1/docs/what-is-a-data-type): Note arrays are not supported; if you have a list of values (for example, email addresses) then you can either delimit multiple values in a string using a suitable character, or provide a separate field for each. - A `Value` or `Metadata` field can have a data type with an underlying `valueType` of `String`, `Int`, `Decimal`, `DateTime` or `Boolean`. - A `SeriesIdentifier` field can only have a data type with an underlying `valueType` of `String` or `DateTime`. ## Subsequent updates LUSID APILuminesceLUSID web app If no records have yet been added to a RDD, you can update any aspect of it by calling the [UpdateRelationalDatasetDefinition](https://www.lusid.com/docs/api/lusid/endpoints/relational-dataset-definition/UpdateRelationalDatasetDefinition) API. If records *have* been added, call the following APIs instead: - The [UpdateRelationalDatasetDetails](https://www.lusid.com/docs/api/lusid/endpoints/relational-dataset-definition/UpdateRelationalDatasetDetails) API to change the `displayName` and `description`, or to add or remove `applicableEntityTypes`. Note you cannot remove an entity type if records are associated with it. - The [UpdateRelationalDatasetFieldSchema](https://www.lusid.com/docs/api/lusid/endpoints/relational-dataset-definition/UpdateRelationalDatasetFieldSchema) API to change the `fieldSchema`. ***Coming soon*** Write a Luminesce SQL query using the [Lusid.RelationalDataset.Definition.Writer](/v1/docs/lusidrelationaldatasetdefinitionwriter) provider and: - To change any aspect of a RDD that has no records, specify `'Update' as WriteAction`. - To add or update fields of a RDD that has records, specify `'Update' as WriteAction`. - To remove fields from a RDD that has records, specify `'RemoveField' as WriteAction`. If records have been added to a RDD, note the following update restrictions to the `fieldSchema`: | Field type | Add new field? | Remove existing field? | Update existing field? | | --- | --- | --- | --- | | `SeriesIdentifier` | ✅ but `required` must be `false` | ❌ | ✅ but note the following: - `required` only to `false` - `dataTypeId` only to the same `valueType` | | `Value` | ✅ | ✅ but at least one must remain with `required` set to `true` | ✅ but note the following: - `required` between `true` and `false` - `dataTypeId` only to the same `valueType` - `category` to `Metadata`, but at least one mandatory `Value` field must remain | | `Metadata` | ✅ | ✅ | ✅ but note the following: - `required` between `true` and `false` - `dataTypeId` only to the same `valueType` - `category` to `Value` | ## Deleting a relational dataset definition Note any records added to the dataset are also deleted, and can only be retrieved by rolling back the `asAt` timeline [when querying](/v1/docs/how-do-i-query-a-custom-dataset). LUSID APILuminesceLUSID web app Call the [DeleteRelationalDatasetDefinition](https://www.lusid.com/docs/api/lusid/endpoints/relational-dataset-definition/DeleteRelationalDatasetDefinition) API and specify the scope and code of the RDD in the URL, for example: ```json curl -X POST 'https://.lusid.com/api/api/relationaldatasetdefinitions/MyRDDs/Addresses'  -H 'Content-Type: application/json-patch+json'  -H 'Authorization: Bearer ' ``` ***Coming soon*** Write a Luminesce SQL query using the [Lusid.RelationalDataset.Definition.Writer](/v1/docs/lusidrelationaldatasetdefinitionwriter#example-3-delete-a-rdd) provider and specify `'Delete' as WriteAction`.