Updating a collection from outside Graxeon

A collection on S3-compatible storage is just .kgl files sitting in a bucket prefix. Anything that can write an object to that bucket can update your knowledge graph — Studio isn't the only writer. This page covers four ways teams do that in practice.

This applies to collections using S3-compatible storage (AWS S3, MinIO, Cloudflare R2, etc). If you haven't connected a bucket yet, start with Connecting an S3 bucket.

The layout

Every collection lives under a fixed prefix, so an external writer always knows exactly where to put a file:

collections/<collection id>/<filename>.kgl     — data files
collections/<collection id>/schemas.kgl        — schema definitions
collections/<collection id>/assets/<key>       — images, files, etc.

Any object ending in .kgl dropped under that prefix (other than schemas.kgl itself) is picked up automatically — there's no registration step. Split output into as many files as you like; a common convention is one file per import batch (e.g. import_2026-07-10.kgl) so unrelated writers never touch the same object.

1. Direct SDK or CLI writes

The most direct path: any script, scheduled job, or data pipeline that can call PutObject can add nodes to a live collection. A nightly export from a database, CRM, or spreadsheet can be turned into KGL and pushed straight to the bucket with the AWS CLI:

aws s3 cp import_2026-07-10.kgl \
  s3://your-bucket/collections/your-collection-id/import_2026-07-10.kgl

or with boto3 from inside the pipeline itself:

import boto3

s3 = boto3.client("s3")
s3.put_object(
    Bucket="your-bucket",
    Key="collections/your-collection-id/import_2026-07-10.kgl",
    Body=kgl_text.encode("utf-8"),
)

Before pushing, validate the output against the collection's schema with the kgl CLI (from the kgl-lang package) — it catches malformed files or schema mismatches before they ever reach the bucket:

kgl lint ./local-copy-of-collection

2. Git as the source of truth

Because KGL is plain text, it diffs and reviews cleanly in a normal pull request. Teams that want change history and review on their knowledge graph keep the collection in a git repo and treat the bucket as a deploy target: a CI job lints the graph and syncs it to S3 on merge.

# .github/workflows/publish.yml
- run: kgl lint ./collection
- run: aws s3 sync ./collection s3://your-bucket/collections/your-collection-id/ --delete

This gets you PR review, blame, and rollback on the graph itself, on top of whatever Studio/Explorer already give you at the UI level.

3. Mount the bucket as a filesystem

Since the storage backend works against any S3-compatible endpoint, tools like rclone can mount the bucket as a regular folder:

rclone mount your-remote:your-bucket/collections/your-collection-id ./collection --vfs-cache-mode writes

With that mounted, any text editor or IDE can open and save .kgl files directly, no AWS-specific tooling required in the editing loop.

4. GUI S3 clients

For occasional manual edits, any S3 browser works — Cyberduck, S3 Browser, or the AWS Console's own object viewer. Open the file, edit the text, upload it back under the same key.

What to expect after an external write

Changes can take up to 60 seconds to appear. S3-backed collections are cached with a short TTL rather than watched for changes, so an external write lands in Studio/Explorer within a minute rather than instantly.

There's no file locking between writers. S3 writes are atomic per object — a reader never sees a half-written file — but two different writers targeting the same filename will silently overwrite one another rather than merge. Give each external source its own file (per import batch, per pipeline, per integration) and this doesn't come up in practice.