Skip to main content
Version: V1.1.0

FORK TABLE

Description​

The FORK TABLE statement creates a destination table based on a consistent snapshot of a source table. The destination table is logically equivalent to the source table as of the fork time, and can be used as an independent table for subsequent reads and writes. Writes to the source table do not affect the destination table, and vice versa.

Compared with a traditional full copy, FORK TABLE is designed to reduce the cost of cloning large tables by reusing existing data organization and storage structures whenever possible, while preserving snapshot consistency and isolation semantics.

tip

In seekdb V1.1.0, FORK TABLE is provided as an experimental feature and is not recommended for production use.

Privileges​

To execute FORK TABLE, you typically need:

  • Privileges to access the source table (for example, SELECT).
  • Privileges to create tables in the destination database (for example, CREATE).

Additional privileges are required for subsequent DML or DDL operations on the destination table.

Syntax​

FORK TABLE source_table TO destination_table;

Parameters​

ParameterDescription
source_tableThe source table name. You can specify db.table or table (in the current database).
destination_tableThe destination table name. You can specify db.table or table (in the current database).

Behavior​

  • Snapshot consistency: The destination table reflects a consistent snapshot of the source table at the fork time. Subsequent changes to the source table do not affect the destination table.
  • Read/write isolation: The destination table is independent of the source table. Writes to either table do not affect the other.
  • Progressive availability: The destination table can become available before the system finishes background work. This does not change the user-visible snapshot and isolation semantics.
  • Performance characteristics: In typical small-scale scenarios, FORK TABLE can create the destination table and make it available within hundreds of milliseconds. In scenarios such as large transactions, complex data shapes, or tight resources, background work may take longer.

Limitations and considerations​

In seekdb V1.1.0, FORK TABLE has the following limitations and considerations:

  • Mutual exclusion with DDL: Fork is mutually exclusive with DDL on the source and destination tables until the fork operation finishes. Avoid running CREATE/ALTER/DROP/RENAME concurrently on the involved tables.
  • The destination table must not exist: If the destination table already exists, the statement returns an error. Drop the existing table first.
  • Unsupported object types: Fork is not supported for some object types, including internal tables, temporary tables, materialized views, triggers, foreign keys, and tables in the recycle bin.
  • Index-related limitations:
    • Semantic indexes, IVF indexes, and spatial indexes are not supported.
    • Fork is not supported for partitioned tables that have global indexes.
    • Indexes cannot be built as part of the fork build process. If you need to change indexing strategy, create or adjust indexes on the destination table after the fork completes.
    • If the source table contains an HNSW vector index, the fork may increase memory usage. Run a small-scale validation first and plan capacity accordingly.
  • Storage format limitation: Fork is not supported for column-store tables.

Examples​

Example 1: Create a forked table and run queries​

-- Create a forked table
FORK TABLE t1 TO t1_fork;

-- Query the forked table
SELECT COUNT(*) FROM t1_fork;

-- Write to the forked table (writes do not affect the source table)
INSERT INTO t1_fork VALUES (...);

Example 2: Data versioning and branching (rollback/promotion)​

-- 1) Create a branch table (baseline is the snapshot at fork time)
FORK TABLE t1 TO t1_branch_v2;

-- 2) Make changes on the branch table
UPDATE t1_branch_v2 SET feature = 'new_value' WHERE id = 1;
CREATE INDEX idx_feature ON t1_branch_v2(feature);

-- 3a) Roll back: stop using the branch (example: drop the branch table)
DROP TABLE t1_branch_v2;

-- 3b) Promote: switch the branch to become the default (example: atomic rename)
-- NOTE: This operation renames table objects. Make sure you understand the impact and have the required privileges.
RENAME TABLE t1 TO t1_branch_backup, t1_branch_v2 TO t1;
DROP TABLE t1_branch_backup;

Example 3: A/B testing and sandbox validation​

-- Create an experiment table based on a production snapshot
FORK TABLE t_search_prod TO t_search_exp;

-- Make changes and evaluate on the experiment table
-- ...

-- If the experiment fails, drop the experiment table
DROP TABLE t_search_exp;

FAQ​

Q1: After the fork completes, do future changes to the source table affect the destination table?​

No. The destination table is created from a consistent snapshot at fork time. Subsequent changes to the source table do not affect the destination table.

Q2: Do writes to the destination table affect the source table?​

No. The destination table is independent of the source table. Writes to either table do not affect the other.

Q3: Why can the destination table be used before the fork fully finishes?​

The system prioritizes making the destination table available. Background work may continue, but the user-visible snapshot and isolation semantics remain consistent. And FORK TABLE tries to reuse existing data organization and storage structures during the creation process. It can usually maintain a fast creation speed in large table scenarios.

Q4: How is FORK TABLE different from a traditional table copy?​

FORK TABLE is designed to avoid a full data copy by reusing existing data organization and storage structures whenever possible, while preserving snapshot consistency and isolation semantics.

Contents

Edit this page