Filesystem Tables And Uploads

Filesystem tables

sources:
  - name: documents
    kind: file
    backend: s3
    bucket: app-documents
    prefix: tenants/${account_id}
    presign_ttl: 15m
    capabilities:
      files.list: true
      files.read: true
      files.write: false

Every filesystem table exposes stable columns such as key, size, content_type, etag, modified_at, url, and data.

query {
  documents(prefix: "reports/", first: 20, order_by: { key: asc }) {
    key
    size
    content_type
    url
  }
  documents_cursor
}

Uploads

Uploads accept multipart requests on /api/v1/graphql. Files can either be inlined as base64 variables or streamed into a configured filesystem table.

mutation ($file: Upload!) {
  documents(insert: { file: $file }) {
    key
    size
    url
  }
}

When uploads.storage names a filesystem table, the upload handler streams the file into the backend and replaces the variable with object metadata instead of base64 file data.

Policy

Filesystems participate in source capabilities and read-only policy. Use read-only defaults for discovery surfaces and enable writes deliberately.

Read-only filesystems block managed writes and watchers. S3/GCS presigned URLs are cache-bounded so GraphJin does not serve stale URLs past their TTL.