Snapshots and Forks

Snapshots and forks extend traditional object versioning beyond individual objects.

• Snapshots capture the state of an entire bucket at a specific point in time.
• Forks let you clone a snapshot of a bucket, reusing objects without copying data.

Together, they provide powerful tools for data recovery, branching workflows, AI agent workflows, and efficient experimentation. Read more about snapshots and forks in the buckets documentation.

Tigris SDK provides a way to create and manage snapshots and forks using a simple API.

Create a bucket with snapshots enabled

A bucket with snapshots enabled can be created using the createBucket function.

import { createBucket } from "@tigrisdata/storage";

const result = await createBucket("llm-base", {
  enableSnapshot: true,
});

if (result.error) {
  console.error("error creating bucket", result.error);
} else {
  console.log("bucket created with snapshots enabled");
}

Snapshots

Create a snapshot from the bucket

A snapshot can be created from the bucket using the createBucketSnapshot function.

import { createBucketSnapshot } from "@tigrisdata/storage";

await createBucketSnapshot("llm-base", {
  name: "pre-finetune", // optional name for the snapshot
});

List snapshots of a bucket

A list of snapshots for the bucket can be retrieved using the listBucketSnapshots function.

import { listBucketSnapshots } from "@tigrisdata/storage";

const result = await listBucketSnapshots("llm-base");

if (result.error) {
  console.error("Error listing snapshots:", result.error);
} else {
  console.log("Snapshots:");
  result.data.forEach((snapshot) => {
    console.log(`- ${snapshot.version}: ${snapshot.creationDate}`);
  });
}

List objects in a snapshot

Objects in a snapshot can be listed using the list function.

import { list } from "@tigrisdata/storage";

const result = await list("llm-base", {
  snapshotVersion: "1760550614083112540",
});

Forks

Fork is a new bucket created from an existing one, sharing data without duplication.

Create a fork from the bucket

Forks can be created using the createBucket function and by passing sourceBucketName in the options.

import { createBucket } from "@tigrisdata/storage";

const createFork = await createBucket(
  "llm-fork", // name of the fork bucket being created
  {
    sourceBucketName: "llm-base", // name of the fork parent bucket
  },
);

if (createFork.error) {
  console.error("error creating bucket fork", createFork.error);
} else {
  console.log("bucket fork created");
}

Create a fork from the bucket with a specific snapshot

import { createBucket } from "@tigrisdata/storage";

const forkName = "llm-fork";
const sourceBucketName = "llm-base";
const sourceBucketSnapshot = "1760550614083112540";

const fromSnapshot = await createBucket(forkName, {
  sourceBucketName: sourceBucketName,
  sourceBucketSnapshot: sourceBucketSnapshot,
});

if (fromSnapshot.error) {
  console.error("error creating bucket fork", fromSnapshot.error);
} else {
  console.log("bucket fork created");
}

note

If you don't provide the bucket name in the sourceBucketName parameter, it will use the bucket name from either .env or environment variables.

import { createBucketSnapshot, listBucketSnapshots } from "@tigrisdata/storage";

await createBucketSnapshot({
  name: "pre-finetune", // optional name for the snapshot
});

await listBucketSnapshots();

Getting an object from a snapshot

An object from a snapshot can be retrieved using the get function.

import { get } from "@tigrisdata/storage";

const result = await get("object.txt", {
  snapshotVersion: "1760550614083112540",
});

Similarly, head function can be used to get the metadata of an object from a specific snapshot.

import { head } from "@tigrisdata/storage";

const result = await head("object.txt", {
  snapshotVersion: "1760550614083112540",
});