--- title: "Drive.SaveAs" slug: "drivesaveas" updated: 2026-06-30T11:34:26Z published: 2026-06-30T11:34:26Z canonical: "support.lusid.com/drivesaveas" --- > ## 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. # Drive.SaveAs | Type | Read/write | Author | Availability | | --- | --- | --- | --- | | [Direct provider](/v1/docs/what-are-a-data-provider-and-a-direct-provider#direct-provider) | Write | FINBOURNE | Provided with LUSID | The `Drive.SaveAs` provider enables you to write a [Luminesce query](/v1/docs/understanding-the-luminesce-sql-query-syntax) that writes data to one or more files of a particular type in [Drive](/v1/docs/drive). At the time of writing, you can create the following file types: CSV, SqLite, JSON, XML, Parquet, [Excel](/v1/docs/drivesaveas#example-6-generate-an-excel-file-from-an-excel-template), [Word](/v1/docs/drivesaveas#example-7-generate-a-word-file-from-a-word-template), [PDF](/v1/docs/drivesaveas#example-8-generate-a-pdf-file-from-a-pdf-template). `Drive.SaveAs` accepts any number of input variables representing tables of data, and writes each one to a separate file by default. You can change this to combine multiple tables into a single file. Note the folder you write to must exist in Drive. If files with the same name already exist, they are overwritten. **See also:** [Drive.File](/v1/docs/drivefile) ## Basic usage ```sql @data = select ; @x = use Drive.SaveAs with @data enduse; select * from @x ``` ## Options `Drive.SaveAs` has options that enable you to refine a query. > **Note:** The `--path` option is mandatory. The `--fileNames` option is also mandatory and, if writing to multiple files, must be specified last in the list with file names placed on separate lines underneath; see below for examples. The `-type` option is mandatory if you want to create a file type other than CSV. An option takes the form `--<option>=<value>`, for example `--fileNames=trade-file`. Note no spaces are allowed either side of the `=` operator. If an option takes a boolean value, then specifying that option (for example `--ignoreOnZeroRows`) sets it to True; omitting the option specifies False. Current options at article update time are listed in the table below. For the very latest information, run the following query using a [suitable tool](/v1/docs/what-tools-are-available-to-write-luminesce-queries) and examine the online help: ```sql @x = use Drive.SaveAs enduse; select * from @x ``` | Current options | Explanation | | --- | --- | | `type` | The file types to create; also controls file extensions if not specified. [`Csv`, `Excel`, `SqLite`, `Json`, `Xml`, `Parquet`, `Word`, `Pdf`, `RawText`, `JsonWithLineage`, Default: `Csv`] | | `combineToOne` | Combine all files into one when saving. For CSVs this will produce a zipped file. Provide the name to give this file. [String] | | `ignoreOnZeroRows` | Flag to say: if a file would have zero rows, do not write it at all. [Boolean] | | `splitGroupBy` | Splits the given data tables on these fields (a comma delimited list). Each unique 'key set' then will be saved as its own file. The field names here must appear in all tables being saved and should be used in the file name template, for example: `--splitGroupBy=Abc,Xyz` `--fileNames` `f_{Abc}_{Xyz} ` [String] | | `splitGroupByExcludeKeyColumns` | When using `--splitGroupBy` the key columns should be omitted in the output. [Boolean] | | `fileNames` | **Mandatory**. File names (without a path). One per table of data is required. These can be something other than file names as such depending on other options, for example: - Worksheet names when saving to a .xlsx with `--combineToOne` - `<WorksheetName>:<Range[*]>` Range is a table name or named-range-name or raw-range like `A2:B4` when saving to .xlsx from a template, where `*` means ‘don't include the header’. [String] | | `path` | **Mandatory**. The location to save this within the target file store. [String] | | `noAutoFileNameExtension` | Do not automatically append the file extension to the file names provided. [Boolean] | | `dateFormat` | The format string to apply when saving dates (dates with no time component). Used only with some export types. [String, Default: `yyyy-MM-dd`] | | `dateTimeFormat` | The format string to apply when saving date-times (e.g. `yyyy-MM-dd'T'HH:mm:ss.fff`). Used only with some export types. [String, Default: `yyyy-MM-dd HH:mm:ss`] | | `templatePath` | The path and file name within the target file store, from which to fetch a ‘template file’. Only supported by Excel, Word, PDF and CSV. For CSV you may specify '`Blank`' to append to an empty file, otherwise it will append to the template, which must exist. [String] | | `editable` | Make the resulting file editable. Only supported by PDF. The default is `false`. [Boolean] | | `allowCorruptedPdfTemplate` | Use a corrupted PDF template despite form fields being unwritable. Useful if you require a table to be appended to the end of a corrupted PDF. Only supported by PDF. [Boolean] | | `delimiter` | Sets the field delimiter. Only supported by CSV. [String, Default: ,] | | `escape` | Sets the field escape character (must be a single character). Only supported by CSV. [String, Default: `"`] | | `quote` | Sets the field quote character (must be a single character). Only supported by CSV. [String, Default: `"`] | | `excludeHeader` | Should the header row not be included? Only supported by CSV and Excel. [Boolean] | | `alwaysQuote` | Should values always be quoted? Only supported by CSV. [Boolean] | | `encoding` | Specific name of a file encoding. Only supported by `Csv`, `Json`, `JsonWithLineage` and `RawText`. Supported are: `utf-16`, `utf-16BE`, `utf-32`, `utf-32BE`, `us-ascii`, `iso-8859-1`, `utf-8`, `utf-8-no-bom`, `utf-16-no-bom`, `utf-16be-no-bom`, `utf-32-no-bom`, `utf-32be-no-bom` [String] | ## Examples In the following examples, the `select * from @x` syntax at the end generates a report of actions performed. The report contains an `AdditionalInformation` column with a GUID identifying the output file in Drive. Note you can distribute the file to users with suitable Drive permissions using a URL of the form `https://<your-domain>.lusid.com/app/data-management/drive/<guid>?type=file`. ### Example 1: Write a table of data to a CSV file `Csv` is the default file format if the `--type` option is omitted. Note that specifying `/` for the `--path` option creates a file in the root Drive folder, which is guaranteed to exist. The `—alwaysQuote` option encapsulates all values in double quote `"` marks in CSV files only. ```sql @data = select distinct TableName from Sys.Field order by 1; @x = use Drive.SaveAs with @data --path=/ --alwaysQuote --fileNames=myfile enduse; select * from @x ``` ### Example 2: Write a table of data to a different file type Supported file types other than `Csv` at the time of writing are `Excel`, `Sqlite`, `Xml`, `Json`, `Parquet`, `Word`, `Pdf`. ```sql @data = select distinct TableName from Sys.Field order by 1; @x = use Drive.SaveAs with @data --path=/luminesce/testing --type=Excel --fileNames=myfile enduse; select * from @x ``` ### Example 3: Write multiple tables of data to multiple files The number of file names written must match the number of input tables. Note that `mydata1file` and `mydata2file` are on separate lines underneath the `--fileNames` option, which is specified last. ```sql @data1 = select distinct TableName from Sys.Field order by 1; @data2 = select distinct TableName, FieldName from Sys.Field order by 2; @x = use Drive.SaveAs with @data1, @data2 --path=/luminesce/testing --fileNames mydata1file mydata2file enduse; select * from @x ``` ### Example 4: Write multiple tables of data to a single ZIP file containing two files If `--type` is `Csv` (the default) or `Json`, combining multiple tables using the `--combineToOne` option creates a ZIP file containing separate files for each table. ```sql @data1 = select distinct TableName from Sys.Field order by 1; @data2 = select distinct TableName, FieldName from Sys.Field order by 2; @x = use Drive.SaveAs with @data1, @data2 --path=/luminesce/testing --combineToOne=mysinglezipfile --fileNames mydata1file mydata2file enduse; select * from @x ``` ### Example 5: Write multiple tables of data to a single file If `--type` is `Excel` or `Sqlite`, then each table is given a separate tab in a single spreadsheet, or separate tables in a single database file, respectively. Names of tabs/tables are controlled by the `--fileNames` option. ```sql @data1 = select distinct TableName from Sys.Field order by 1; @data2 = select distinct TableName, FieldName from Sys.Field order by 2; @x = use Drive.SaveAs with @data1, @data2 --path=/luminesce/testing --type=Excel --combineToOne=mysinglespreadsheetfile --fileNames mydata1tab mydata2tab enduse; select * from @x ``` ### Example 6: Generate an Excel file from an Excel template If `--type` is `Excel`, the `--templatePath` option generates an Excel XSLX file from an Excel XLTX template file stored in Drive. For example, you could upload the following holdings report template to Drive: [](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/holdingsReportTemplate.xltx)holdingsReportTemplate74.80 KB[](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/holdingsReportTemplate.xltx) You can write a query specifying the holdings data you want to populate the table with and write the completed Excel document to Drive: - Specify `--type=Excel` and provide the `--templatePath` to the Excel template in Drive. - Provide the output path and filename for the completed Excel file using `--path` and `--combineToOne`. - Use the `--fileNames` option to specify that the data should be added to the `HoldingsData` table within the `Holdings` sheet in your Excel file. ```sql -- Generate holdings for the last seven days at 12pm @@x = select Date('now', '-7 day'); @@y = select DateTime(Date('now'), Time('12:00')); @holdings = select    PortfolioScope as Fund,    PortfolioCode as Portfolio,    LusidInstrumentId as Instrument,    Units,    CostAmountPortfolioCurrency from Lusid.Portfolio.Holding where PortfolioScope = 'Finbourne-Examples'  and PortfolioCode = 'EU'  and EffectiveFrom = @@x  and EffectiveAt   = @@y; @x = use Drive.SaveAs with @holdings --path=/luminesce --templatePath=/luminesce/testing/holdingsReportTemplate.xltx --type=Excel --combineToOne=ACME_Holdings_Report.xlsx --fileNames Holdings:HoldingsData enduse; select * from @x ``` The query outputs the following Excel document in Drive, with the table populated: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-LI5TUVMU.png) ### Example 7: Generate a Word file from a Word template You can upload a Word template as a DOTX file to Drive and then use `Drive.SaveAs` to generate a Word document as a DOCX file from the Word template. When creating your template, note: - Any text fields you want your query to fill out should be written in the template as `{{<your-field-name>}}`. - You must give any table you want your query to fill out a title via **Table Properties**. [See how to do this.](https://support.microsoft.com/en-us/office/set-or-change-table-properties-3237de89-b287-4379-8e0c-86d94873b2e0#__toc5) In this example, let's imagine you upload a Word template containing the following fields to Drive: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/79b06314-5465-4313-ab7f-21c87f793e69.png) You can now write a query specifying the data you want to populate each field with and write the completed Word document to Drive: - Specify `--type` is `Word` and provide the `--templatePath` to the Word template in Drive. - Use the `--fileNames` option to specify that the table `@TABLE_DATA` should be appended to the table with title `TABLE_DATA` in your Word template. - Create a table of `@TEXT_VALUES`, on each line specifying the name of a field in the template and providing a value to populate that field with. For instance, you might request that the `TITLE` field is populated with “Providers”. - Map `@TEXT_VALUES` to the specific `--fileNames` option `Text:REPLACEMENTS`. This tells `Drive.SaveAs` that `@TEXT_VALUES` contains lines of text to populate multiple fields with, rather than a single table to fill a single table field (which the provider expects by default). ```sql @TABLE_DATA = select distinct TableName from Sys.Field order by 1 limit 20; @TEXT_VALUES = values    ('DATE', '16/02/2023'),    ('TITLE', 'Providers'),    ('DETAIL', 'This document contains a current list of the first 20 Luminesce providers.'),    ('TABLE_CAPTION', 'A table of Luminesce providers'); @doc = use Drive.SaveAs with @TABLE_DATA, @TEXT_VALUES --templatePath=WordTemplate.dotx --path=/luminesce/testing --type=Word --combineToOne=MyCompleteWordDoc.docx --fileNames TABLE_DATA Text:Replacements enduse; select * from @doc; ``` The query outputs the following Word document in Drive, with each field populated: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/392bfaf6-9a9f-49d7-b180-da20ac148614.png) ### Example 8: Generate a PDF file from a PDF template You can upload a PDF template which contains form fields to Drive and then use `Drive.SaveAs` to fill out and store a completed form. In this example, let's imagine you upload a PDF template containing the following form fields to Drive (the PDF template in this example was created using DocFly, other options are available e.g. Adobe Acrobat): ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/db53b271-2e16-4226-9a7e-95eb405155d1.png) You can now write a query specifying the data you want to populate each form field with and write the completed form to Drive: - Specify `--type` is `Pdf` and provide the `--templatePath` to the PDF template in Drive. - Use the `--fileNames` option to specify that the table `@TABLE_DATA` should be appended to the form field key `TABLE_DATA` in your PDF template. - Create a table of `@FIELD_VALUES`, on each line specifying the key of a form field in the template and providing a value, font and font size to populate that form field with. For instance, you might request that the `ADDRESS` form field is populated with “123 Main Street” in the font Liberation Sans, font size 14. - Map `@FIELD_VALUES` to the specific `--fileNames` option `Text:REPLACEMENTS`. This tells `Drive.SaveAs` that `@FIELD_VALUES` contains lines of text to populate multiple form fields with, rather than a single table to fill a single form field (which the provider expects by default). Note the following: - The form field to which each table of data is appended in the PDF template is controlled by the `--fileNames` option. For the provider to correctly map your table of data to the intended form field, the order of your tables in `use Drive.SaveAs with <your-tables>` must match the order of your `--fileNames`. - If a form field is not specified for a table of data, the table is appended to the end of the PDF. - Font and font size default to Liberation Sans, font size 11 if set to `Null` or not specified. ```sql @TABLE_DATA = select distinct TableName from Sys.Field order by 1 limit 20;     @FIELD_VALUES = values    ('COMPANY', '123456789', 'Liberation Sans', 14),    ('ADDRESSEE', 'Acme Co.', Null, 12),    ('NAME', 'Jane Doe', Null, 12),    ('ADDRESS', '123 Main Street', 'Liberation Sans', 14); @PDF_DOCUMENT = use Drive.SaveAs with @FIELD_VALUES, @TABLE_DATA --templatePath=/luminesce/testing/pdfTemplateWithFormFields.pdf --type=Pdf --path=/PDF_Templates/ --combineToOne=myPdf.pdf --fileNames Text:REPLACEMENTS TABLE_DATA enduse; select * from @PDF_DOCUMENT ``` The query outputs the following form in Drive, with each form field populated:![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/7a08f3a2-31ba-4131-beb9-7e34f0227ca7.png)