Workspace Migrations

Workspace Migrations are C# scripts designed to evolve your graph's data and schema over time. Similar to database migrations in traditional software development, they allow you to perform one-time updates, data cleanups, or schema transformations in a controlled and tracked manner.

Migrations are useful for:

• Propagating schema changes (e.g., renaming fields, moving data) from development to production.
• Bulk updating nodes (e.g., normalizing data formats).
• Seeding initial data or configuration.
• Triggering complex re-indexing or data enrichment workflows.

Migration Task Node

Migrations are stored in the graph as nodes of type _MigrationTask. This allows the system to track their execution status and ensure they are not run multiple times unintentionally.

Admins can create, manage, trigger, and monitor the progress of migrations through the Advanced > Migrations interface in the Curiosity Workspace settings. This UI provides a way to view the status, logs, and error messages for each migration task.

File-Based Configuration

When managing workspace customizations via file export/import (e.g., using a Git repository), migrations are stored in the code/migration-tasks directory of the export zip or folder structure.

Each migration file typically contains the metadata attributes and the code to run.

Execution Scope

Migrations run in a specialized MigrationCodeExecutionScope. This scope provides access to the graph and utility tools necessary for performing data operations.

The following objects are available within a migration script:

Object	Type	Description
Graph / G	Mosaik.GraphDB.Safe.Graph	Provides thread-safe read/write access to the graph.
Q() / Query()	IQuery	Entry point for the fluent query builder to find data.
Progress	IProgressReporter	Use Progress.Set(count, total) and Progress.Message("...") to report status to the UI.
Logger	ILogger	Standard logging interface for information, warnings, and errors.
CancellationToken	CancellationToken	Token to check if the migration has been cancelled.
IsCancellationRequested	bool	Returns true if cancellation has been requested.
ThrowIfCancellationRequested()	void	Throws OperationCanceledException if cancellation has been requested.
ChatAI	ChatAI	Helper for interacting with configured AI providers.
Tracker	QueryTracker	Shared performance tracker for all queries created in this scope.
UID(string)	UID128	Parses a UID string into a UID128 value.
RunEndpointAsync<T>(endpointName, ...)	Task<T>	Executes a custom endpoint by name and returns its result.
RunToolAsync(toolUID, functionName, ...)	Task<ToolCallResult>	Executes a registered AI tool by UID and function name.

Lifecycle

1. Creation: A migration is defined (via UI or import) with Status set to Created.
2. Trigger: Migrations can be triggered manually via the management interface or automatically on startup if TriggerRunOnStartup is true.
3. Execution:
   • The system compiles the MigrationCode.
   • The status updates to Running.
   • The code executes.
4. Completion:
   • If successful, status becomes CompletedSuccessfully.
   • If an exception occurs, status becomes Failed, and ErrorMessage is populated.

Once a migration is CompletedSuccessfully, it will not run again automatically on startup.