File - Upload & DataType

KalamDB separates file metadata from file bytes:

• SQL rows store FILE references in table columns.
• Binary content is uploaded/read through file APIs.

This allows database queries and file transfer to scale independently while preserving table-level security.

Upload and Read Flow

1. Client sends SQL using FILE("placeholder").
2. Client attaches multipart file part as file:<placeholder>.
3. KalamDB validates auth and table type (USER / SHARED only).
4. Binary is persisted in the table’s storage path.
5. Row stores a file reference payload used for future reads/downloads.

For endpoint details, see HTTP Reference.

USER vs SHARED Pathing Model

KalamDB routes file bytes according to table type:

• USER tables: file objects are stored under the authenticated user’s tenant scope.
• SHARED tables: file objects are stored under shared table scope.

This matches KalamDB’s tenant-aware architecture:

• user-private data stays isolated in user-tenant paths
• shared assets are accessible through shared-table policy

SYSTEM and STREAM table paths are not valid for file APIs.

Backend-Verified Path Resolution

From backend implementation (kalamdb-filestore + API handlers):

• For USER tables, file operations are resolved with user_id context.
• For SHARED tables, file operations are resolved without user_id context.
• Download handler enforces this behavior and rejects STREAM/SYSTEM file access.

Default storage templates are:

• shared_tables_template = "{namespace}/{tableName}"
• user_tables_template = "{namespace}/{tableName}/{userId}"

So for a table chat.attachments:

• shared path example: chat/attachments/<subfolder>/<file_id>
• user path example: chat/attachments/<userId>/<subfolder>/<file_id>

Templates are configurable per storage with CREATE STORAGE / ALTER STORAGE, but the user-scoped resolution model remains the same.

Architecture Diagram

Why This Design Helps

• Keeps tenant boundaries explicit for uploads and reads.
• Avoids mixing user-private files with shared table assets.
• Lets applications query metadata with SQL while streaming bytes through file endpoints.

Related Docs

• FILE Datatype
• Table Types
• Storage ID Usage