--- title: "Lusid.Instrument.Writer" slug: "lusidinstrumentwriter" updated: 2026-06-30T09:12:25Z published: 2026-06-30T09:12:25Z canonical: "support.lusid.com/lusidinstrumentwriter" --- > ## 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.Instrument.Writer | **Type** | **Read/write** | **Author** | **Availability** | | --- | --- | --- | --- | | [Data provider](/v1/docs/what-are-a-data-provider-and-a-direct-provider) | Write | FINBOURNE | Provided with LUSID | The `Lusid.Instrument.Writer` provider enables you to write a [Luminesce SQL query](/v1/docs/understanding-the-luminesce-sql-query-syntax) to create, update or delete [instruments](/v1/docs/instruments) of any asset class in LUSID. > **Note**: This provider **does not create full economic definitions** for instruments. While it may be useful for rapid prototyping, not all LUSID analytical functionality is subsequently available for these instruments. **We recommend using dedicated writer providers for individual asset classes instead**. [More information](/v1/docs/lusidinstrumenttypewriter-providers). If you do choose to use `Lusid.Instrument.Writer`, you must construct a valid table of data to write, one instrument per record. The provider lists the fields (columns) available to populate with values for each record, and has a set of parameters to help you construct a valid table. Your query can use the `WriteAction` field to perform one of the following operations on the table of data to write: - Upsert an instrument; that is, update an existing instrument if a value for at least one [unique identifier](/v1/docs/what-are-unique-and-non-unique-identifiers) (such as a FIGI) already exists in LUSID, and create a new instrument if not. This is the default operation if you omit `WriteAction`. Note if you are creating an instrument, make sure to omit a value for the `LusidInstrumentId` field, since a unique [LUID](/v1/docs/what-is-a-lusid-instrument-id-or-luid) will be automatically created for you. - Hard or soft delete an instrument. For more information on the difference, see [this article](/v1/docs/how-do-i-delete-an-instrument). **See also:** [Lusid.Instrument..Writer providers](/v1/docs/lusidinstrumenttypewriter-providers) ## Basic usage ```sql @table_of_data = ; select * from Lusid.Instrument.Writer where toWrite = @table_of_data; ``` ## Query parameters The `Lusid.Instrument.Writer` provider has a set of 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 the following query using a [suitable tool](/v1/docs/what-tools-are-available-to-write-luminesce-queries) (this example lists parameters for bonds, but they are the same for all providers): ```sql select FieldName, DataType, ParamDefaultValue, Description from Sys.Field where TableName = 'Lusid.Instrument.Writer' and FieldType = 'Parameter'; ``` ## Data fields `Lusid.Instrument.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) | `DisplayName` At least one [unique identifier](/v1/docs/what-are-unique-and-non-unique-identifiers), for example `'BBG00WGHTKZ0' as Figi` | If creating, do NOT specify `LusidInstrumentId`. | | Delete | `'HardDelete' as WriteAction` or `'SoftDelete' as WriteAction` | `LusidInstrumentId` | | > [!WARNING] > Warning > > The `Upsert` operation replaces the full instrument record. When updating an instrument, you **must** include any existing fields and values you want to retain - not just the fields you’re changing. To list all available fields for a particular provider, their data types, whether fields are considered 'main', and an explanation for each, run the following query using a [suitable tool](/v1/docs/what-tools-are-available-to-write-luminesce-queries) (this example lists fields for bonds): ```sql select FieldName, DataType, IsMain, IsPrimaryKey, SampleValues, Description from Sys.Field where TableName = 'Lusid.Instrument.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, a `Lusid.Instrument.Writer` provider returns an error code. If an 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 new instrument In this example, LUSID creates a new instrument providing a FIGI of `BBG00WGHTKZ0` does not already exist in the instrument master. Returning the `LusidInstrumentId` field is useful to reveal the unique LUID automatically generated for the new instrument. ```sql @table_of_data = select 'AstraZeneca' as DisplayName, 'BBG00WGHTKZ0' as Figi; select LusidInstrumentId, Figi, DisplayName, WriteErrorCode from Lusid.Instrument.Writer where toWrite = @table_of_data; ``` ### Example 2: Update an existing instrument Following on from Example 1, since a FIGI of `BBG00WGHTKZ0` now exists, the existing instrument is updated with a new display name. Returning the `LusidInstrumentId` field again reveals the instrument has the same LUID, confirming no new instrument has been created. ```sql @table_of_data = select 'AstraZeneca PLC' as DisplayName, 'BBG00WGHTKZ0' as Figi; select LusidInstrumentId, Figi, DisplayName, WriteErrorCode from Lusid.Instrument.Writer where toWrite = @table_of_data; ``` > [!WARNING] > Warning > > `Lusid.Instrument.Writer` performs a full replace of the instrument record, not a partial update. When updating an instrument, the `Upsert` operation clears any existing attributes not included in the `@table_of_data` parameter (such as a configured look-through portfolio). You **must** include all existing values in the `@table_of_data` alongside the fields you’re changing, or they will be removed. ### Example 3: Delete an instrument in a particular scope To delete an instrument, specify its LUID and either `'HardDelete' as WriteAction` or `'SoftDelete' as WriteAction`, for example: ```sql @table_of_data = select 'LUID_00003DFA' as LusidInstrumentId, 'my-custom-instr-scope' as Scope, 'HardDelete' as WriteAction; select * from Lusid.Instrument.Writer where toWrite = @table_of_data; ```