FILE Datatype

KalamDB supports a FILE datatype for storing file references in table rows while the binary content is managed by the file service.

Use this page to understand SQL usage. For architecture and storage-path layout, see File - Upload & DataType.

Define FILE Columns

Create a table with a FILE column:

CREATE TABLE app.documents (
  id BIGINT PRIMARY KEY DEFAULT SNOWFLAKE_ID(),
  title TEXT NOT NULL,
  attachment FILE,
  created_at TIMESTAMP DEFAULT NOW()
) WITH (TYPE = 'USER');

FILE columns are supported on USER and SHARED tables.

Insert with FILE(…)

Use FILE("placeholder") in SQL and send multipart form parts named file:<placeholder>.

INSERT INTO app.documents (id, title, attachment)
VALUES (1001, 'Contract', FILE("contract"));

Multipart body parts:

• sql
• params (optional JSON array string)
• namespace_id (optional)
• file:contract (binary part for FILE("contract"))

Backend behavior (API + file utils):

• SQL multipart parser enforces file limits (max_files_per_request, max_size_bytes).
• Placeholder names in FILE("name") must match multipart keys file:name.
• On SQL failure after staging/finalization, cleanup routines attempt to remove uploaded files.

Query FILE Columns

Querying returns file-reference metadata in the row.

SELECT id, title, attachment
FROM app.documents
WHERE id = 1001;

In SDKs, parse the returned file reference and build download URLs (for example with FileRef in TypeScript).

Download Files

Use the file endpoint:

GET /v1/files/{namespace}/{table_name}/{subfolder}/{file_id}

Notes:

• Bearer token is required.
• SYSTEM and STREAM tables are rejected for file paths.
• user_id may be required for user-table scope resolution.

Path model summary:

• USER table downloads resolve using user scope (user_id effective context).
• SHARED table downloads resolve without user scope.
• Effective folder layout is controlled by storage templates (see architecture page).

Best Practices

• Use USER tables for tenant-private files.
• Use SHARED tables for global/shared assets.
• Store descriptive metadata in additional columns (e.g., mime, label, tags).
• Fetch only required columns where possible (for example SELECT id, attachment).

Related Docs

• HTTP Reference
• FILE Columns & Uploads (TypeScript)
• File - Upload & DataType