FILE Columns & Uploads

kalam-link supports file upload and retrieval patterns for KalamDB FILE columns.

Upload files with SQL

Use queryWithFiles(sql, files, params?, onProgress?):

const avatarFile = fileInput.files?.[0];
if (!avatarFile) throw new Error('No file selected');
 
await client.queryWithFiles(
  'INSERT INTO app.users (id, avatar) VALUES ($1, FILE("avatar"))',
  { avatar: avatarFile },
  ['user_123']
);

Progress callback

In browser environments (XMLHttpRequest available), pass onProgress:

await client.queryWithFiles(sql, files, params, (progress) => {
  console.log(progress.file_name, progress.percent);
});

Auth behavior

From source:

• SDK builds auth header via buildAuthHeader(auth)
• sends multipart request to POST /v1/api/sql
• falls back to fetch when XHR progress is unavailable

FileRef model

file_ref.ts exposes FileRef and helpers:

import { FileRef, parseFileRef, parseFileRefs } from 'kalam-link';

Parse and use file metadata

const ref = parseFileRef(row.attachment);
if (ref) {
  console.log(ref.name, ref.size, ref.mime);
  console.log(ref.formatSize());
  console.log(ref.relativePath());
}

Build download URL

const url = ref.getDownloadUrl('http://localhost:8080', 'app', 'users');

Type helpers

ref.isImage();
ref.isVideo();
ref.isAudio();
ref.isPdf();
ref.getTypeDescription();

Storage-path internals documented by source

FileRef includes:

• id, sub, name, size, mime, sha256, optional shard
• filename sanitization and extension normalization
• shared-table shard-aware relativePath() generation

This is useful for building file galleries, attachment viewers, and audit tooling.