Structured files in Storage

Storage uses one tabular contract for CSV, TSV, and XLSX. Declare it when the file’s expected structure is known, regardless of whether the bytes come from a browser upload or rows generated through uploadPart(). The schema is stored on the upload session and reused when Storage builds the file index. It is not inferred from Excel formatting.

Shared schema contract

{
  schemaPolicy: 'fallback' | 'strict',
  sheets: [
    {
      name: 'Products',
      table: {
        columns: [
          { key: 'sku', header: 'SKU', type: 'string' },
          { key: 'price', header: 'Price', type: 'number' },
          { key: 'createdAt', header: 'Created', type: 'date' },
          { key: 'metadata', header: 'Metadata', type: 'object' },
          { key: 'active', header: 'Active', type: 'boolean' },
        ],
      },
    },
  ],
}

XLSX may declare multiple worksheets.
CSV and TSV accept exactly one logical sheet. Its name identifies the tabular schema; the physical file still has no worksheet tabs.
key is the property returned in each row.
header matches the visible source header and defaults to key when omitted.
column order is stable and shared by row generation and indexed reads.

Column types

Type	Result
`string`	Text is preserved as text
`number`	Compatible numeric values become numbers
`boolean`	Compatible boolean values become booleans
`date`	Compatible date values become typed dates
`object`	JSON object or array text is parsed into an object or array

object deliberately excludes JSON scalar values. A value such as {"segment":"A"} or [1,2] is valid; "A", 12, and malformed JSON are not object-column values. Without a declared type, imported tabular values remain strings. XLSX cell styles, number formats, colors, and formatting never declare the logical type.

Fallback is the default

Use schemaPolicy: 'fallback' for user-provided files and integrations where preserving the upload is more important than rejecting a structural deviation. Fallback behavior is deterministic:

the raw file remains available;
matching declared columns use their declared types;
missing and extra sheets or columns are reported in fileStats.schema.issues;
undeclared columns are retained as strings;
if any non-null value is incompatible with a declared type, the whole column falls back to strings;
incompatible values are never silently replaced with null.

This avoids a mixed column such as [12.5, "invalid"] and keeps the source evidence intact.

const { session, upload } = await storage.createUploadSession({
  name: 'products.xlsx',
  contentTypeHint: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
  uploadMode: 'direct',
  computeStats: 'sync',
  schemaPolicy: 'fallback',
  sheets: [{
    name: 'Products',
    table: {
      columns: [
        { key: 'sku', header: 'SKU', type: 'string' },
        { key: 'price', header: 'Price', type: 'number' },
        { key: 'createdAt', header: 'Created', type: 'date' },
        { key: 'metadata', header: 'Metadata', type: 'object' },
      ],
    },
  }],
});

return {
  storageUploadSessionId: session.storageUploadSessionId,
  upload: {
    url: upload.uploadUrl,
    method: upload.method,
    headers: upload.headers,
  },
};

The client uploads the existing workbook with the returned contract. Storage then applies the declared schema while building the XLSX index. The client does not need to re-create or flatten the workbook.

Strict policy

Use schemaPolicy: 'strict' only when a mismatch must stop structured processing, for example a controlled financial import or a versioned partner feed. Strict policy requires table.columns when the session is created. A missing or additional sheet, missing or additional column, duplicate declaration, or incompatible typed value makes structured indexing fail with STORAGE_TABULAR_SCHEMA_MISMATCH. The raw uploaded file is preserved for download and diagnosis; it is not silently transformed or deleted. Downstream processing must require successful structured indexing before it consumes rows.

Strict validates the declared tabular contract, not business rules such as “price must be positive” or “SKU must exist.” Apply those rules after reading typed rows.

CSV and TSV dialect

CSV and TSV use the same column schema plus optional dialect settings:

const { session } = await storage.createUploadSession({
  name: 'products.tsv',
  contentTypeHint: 'text/tab-separated-values',
  uploadMode: 'incremental',
  computeStats: 'sync',
  schemaPolicy: 'fallback',
  csv: {
    delimiter: '\t',
    recordDelimiter: '\n',
    encoding: 'utf8',
    headerRow: 1,
  },
  sheets: [{
    name: 'Data',
    table: {
      columns: [
        { key: 'sku', header: 'SKU', type: 'string' },
        { key: 'price', header: 'Price', type: 'number' },
      ],
    },
  }],
});

Declare the delimiter and encoding when the source is known. Automatic detection remains available for ordinary imports, but an explicit dialect prevents ambiguity and is reused by indexed reads.

Generate typed rows

For generated CSV/XLSX, parts may contain row objects or positional arrays instead of serialized bytes.

const { session } = await storage.createUploadSession({
  name: 'report.xlsx',
  contentTypeHint: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
  uploadMode: 'incremental',
  writeMode: 'direct',
  computeStats: 'sync',
  sheets: [{
    name: 'Report',
    table: {
      header: true,
      autoFilter: true,
      columns: [
        { key: 'productId', header: 'Product ID', type: 'string' },
        { key: 'price', header: 'Price', type: 'number' },
        { key: 'metadata', header: 'Metadata', type: 'object' },
      ],
    },
  }],
});

const sessionId = session.storageUploadSessionId;

await storage.uploadPart(sessionId, {
  rows: [
    { productId: 'P-1', price: 12.5, metadata: { segment: 'A' } },
    { productId: 'P-2', price: 9.99, metadata: ['sale'] },
  ],
});

const result = await storage.finalizeUploadSession(sessionId);
return { storageEntryId: result.entry.storageEntryId };

Choose the structured writeMode independently from uploadMode:

`writeMode`	Use when
`staged`	Independent requests may be retried, replaced, or reordered; sheets or columns can be inferred; XLSX needs sparse cells, formulas, or dynamic worksheets
`direct`	Every CSV/XLSX column and worksheet is declared before the first row; XLSX parts contain rows only

staged is the safer default for ordinary multi-request writers. Structured direct is for a fixed layout and rejects undeclared worksheets or cell-oriented XLSX parts.

Compute timing

The declared schema is honored in every compute mode:

`computeStats`	Structured index availability
`sync`	Ready when finalization completes
`async`	Queued after the file entry is published
`none`	Built lazily by `getFileStats()` or `getFileData()`

CSV, TSV, and XLSX sessions default to sync. Set the mode explicitly when the next workflow has a strict latency or readiness requirement.

Read the typed result

const page = await storage.getFileData(storageEntryId, {
  sheet: 'Products',
  limit: 2_000,
});

return {
  rows: page.rows,
  columns: page.columns,
  hasMore: page.next,
  nextCursor: page.nextCursor,
};

Omit sheet to use the first visible XLSX worksheet. Omit columns to read every source column. The read-time columns option projects, renames, or casts a result; it does not replace the schema declared on the upload session. Use storage.walkFileData() for a complete scan without accumulating the file in memory:

let total = 0;

await storage.walkFileData(
  storageEntryId,
  { sheet: 'Products' },
  async (rows) => {
    total += rows.length;
  },
  { fullScan: true, batchSize: 2_000 },
);

return { total };

Other structured formats

getFileData() also supports NDJSON/JSONL, JSON arrays, and record-oriented XML. These formats use their native record structure rather than the CSV/TSV/XLSX sheets[].table.columns[] upload schema. XML reads require recordPath.

Next steps

Upload sessions — direct, incremental, and chunked completion rules.
Storage overview — workspaces, access, retention, and lifecycle.
Storage low-code reference — exact reader and writer signatures.

Application interfaces

Data

Files

Automation

Collaboration and realtime

Observability

Identity and security

Structured files in Storage

Shared schema contract

Column types

Fallback is the default

Strict policy

CSV and TSV dialect

Generate typed rows

Compute timing

Read the typed result

Other structured formats

Next steps

​Shared schema contract

​Column types

​Fallback is the default

​Strict policy

​CSV and TSV dialect

​Generate typed rows

​Compute timing

​Read the typed result

​Other structured formats

​Next steps

Shared schema contract

Column types

Fallback is the default

Strict policy

CSV and TSV dialect

Generate typed rows

Compute timing

Read the typed result

Other structured formats

Next steps