---
title: "Lusid.RelationalDataset.Definition.Writer"
slug: "lusidrelationaldatasetdefinitionwriter"
updated: 2026-01-19T15:26:41Z
published: 2026-01-19T15:26:41Z
canonical: "support.lusid.com/lusidrelationaldatasetdefinitionwriter"
---

> ## 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.

# Lusid.RelationalDataset.Definition.Writer

| **Type** | **Read/write** | **Author** | **Availability** |
| --- | --- | --- | --- |
| [Data provider](/v1/docs/what-are-a-data-provider-and-a-direct-provider) | Read | FINBOURNE | Provided with LUSID |

The `Lusid.RelationalDataset.Definition.Writer` provider enables you to write a [Luminesce SQL query](/v1/docs/understanding-the-luminesce-sql-query-syntax) that either creates, updates or deletes one or more [relational dataset definitions](/v1/docs/how-do-i-create-a-relational-dataset-definition) (RDDs).

Your query should use the `WriteAction` field to perform one of the following operations:

- Upsert a RDD (this is the default operation if you omit `WriteAction`). A RDD is created if it does not exist and updated if it does.
- Update a RDD with or without records.
- Remove fields from a RDD with records.
- Delete a RDD.

**See also**: [Lusid.RelationalDataset.Definition](/v1/docs/lusidrelationaldatasetdefinition)

## Basic usage

```sql
@table_of_data = <select-statement>;
select * from Lusid.RelationalDataset.Definition.Writer where ToWrite = @table_of_data;
```

## Query parameters

`Lusid.RelationalDataset.Definition.Writer` has parameters that help you construct a valid table of data to write.

> **Note:** The `ToWrite` parameter is mandatory and used to actually write the table of data into LUSID.

To list available parameters, their data types, default values, and an explanation for each, run a query like this one using a [suitable tool](/v1/docs/what-tools-are-available-to-write-luminesce-queries):

```sql
select FieldName, DataType, ParamDefaultValue, Description from Sys.Field 
  where TableName = 'Lusid.RelationalDataset.Definition.Writer' and FieldType = 'Parameter';
```

## Data fields

`Lusid.RelationalDataset.Definition.Writer` lists the fields you can populate in your table of data to write.

Depending on the operation you want to perform, the following fields are mandatory to include in the table of data:

| **Operation** | **Specify using...** | **Mandatory fields** | **Notes** |
| --- | --- | --- | --- |
| Upsert | `'Upsert' as WriteAction` (or omit) | - `Scope` - `Code` - `ApplicableEntityTypes` ([see list](/v1/docs/how-do-i-create-a-relational-dataset-definition#request-fields)) - `DisplayName` - `FieldCategory` (either `SeriesIdentifier`, `Value` or `Metadata`) - `FieldName` - `FieldDataTypeScope` - `FieldDataTypeCode` - `FieldRequired` (`True` or `False`) | You must specify or retain at least one field with a `FieldCategory` of `Value` and `FieldRequired` as `True`. [More information](/v1/docs/how-do-i-create-a-relational-dataset-definition#request-fields). |
| Insert | `'Insert' as WriteAction` |
| Update | `'Update' as WriteAction` |
| Removing fields (only if a RDD has records) | `'RemoveField' as WriteAction` | - `Scope` - `Code` - `FieldName` | You cannot remove `SeriesIdentifier` fields, nor the last mandatory `Value` field. [More information](/v1/docs/how-do-i-create-a-relational-dataset-definition#subsequent-updates). |
| Delete | `'Delete' as WriteAction` | - `Scope` - `Code` | Deleting a RDD deletes all records. |

To list all available fields, their data types, whether fields are considered 'main', and an explanation for each, run a query like this using a [suitable tool](/v1/docs/what-tools-are-available-to-write-luminesce-queries):

```sql
select FieldName, DataType, IsMain, IsPrimaryKey, SampleValues, Description from Sys.Field 
  where TableName = 'Lusid.RelationalDataset.Definition.Writer' and FieldType = 'Column';
```

## Write errors

We recommend examining the results of every write query using one or more of the `WriteError`, `WriteErrorCode` and `WriteErrorDetail` fields.

For each record in the table of data to write, an error code is returned. If the operation is successful, the error code is `0`. If unsuccessful, a positive error code and explanation help you discover why LUSID considers the operation invalid.

## Examples

> **Note:** For more example Luminesce SQL queries, visit our [Github repo](https://github.com/finbourne/luminesce-examples/tree/master/examples).

### Example 1: Create a RDD

You must specify at least one field with a `FieldCategory` of `Value` and `FieldRequired` as `True`. You can specify up to 99 other `SeriesIdentifier`, `Value` or `Metadata` fields, which can be mandatory or optional. [More information](/v1/docs/how-do-i-create-a-relational-dataset-definition#request-fields).

```sql
@fields = values
('AddressType', 'SeriesIdentifier', 'MyRDDs', 'AddressTypes', True),
('Street', 'Value', 'system', 'string', True),
('City', 'Value', 'system', 'string', False),
('Email', 'Metadata', 'system', 'string', False)
;

@data_to_write = select 
  'MyRDDs' as Scope,
  'Addresses' as Code,
  'LegalEntity,Person' as ApplicableEntityTypes,
  'Addresses' as DisplayName,
  column1 as FieldName,
  column2 as FieldCategory,
  column3 as FieldDataTypeScope,
  column4 as FieldDataTypeCode,
  column5 as FieldRequired from @fields
;
select * from Lusid.RelationalDataset.Definition.Writer
  where ToWrite = @data_to_write;
```

### Example 2: Remove fields from a RDD with records

You cannot remove `SeriesIdentifier` fields, nor the last mandatory `Value` field. [More information](/v1/docs/how-do-i-create-a-relational-dataset-definition#subsequent-updates).

**Note**: To remove fields from a RDD that has no records, use `'Update' as WriteAction` and specify just the fields you want to retain.

```sql
@fields = values
('City'),
('Email')
;

@data_to_write = select 
  'RemoveField' as WriteAction,
  'MyRDDs' as Scope,
  'Addresses' as Code,
  column1 as FieldName from @fields
;
select * from Lusid.RelationalDataset.Definition.Writer
  where ToWrite = @data_to_write;
```

### Example 3: Delete a RDD

You must specify `'Delete' as WriteAction`. Note any records are also deleted.

```sql
@data_to_write = select
  'Delete' as WriteAction, 
  'MyRDDs' as Scope, 
  'Addresses' as Code
;
select * from Lusid.RelationalDataset.Definition.Writer 
  where ToWrite = @data_to_write;
```