Labels

Labels are flexible tags you can attach to any entity (change sets, files, versions, paragraphs, JSON properties, and more). Each label has an id and a name (e.g. important, urgent, checkpoint).

Common Use Cases

Categorization:

• Tag files by importance: important, draft, reviewed
• Tag changes by type: type:feature, type:bugfix, type:refactor

Workflows:

• Track status: status:review, status:approved, status:rejected
• Priority management: priority:high, priority:low
• Release milestones: release:v1.2.0, release:v2.0.0

Filtering:

• Query all files labeled important
• Find all change sets with status:review
• Filter entities by multiple labels

Basic Usage

Prefer the high-level SDK helpers when working with labels. They work uniformly across all entity types.

import { openLix, createLabel, attachLabel, detachLabel } from "@lix-js/sdk";

const lix = await openLix({});

// Create or look up a label (labels are global)
const important = await createLabel({ lix, name: "important" });

// The target can be ANY entity. Provide its composite id:
const entity = {
  entity_id: "doc_123",
  schema_key: "markdown_paragraph",
  file_id: "README.md",
};

// Attach
await attachLabel({ lix, entity, label: { id: important.id } });

// Detach
await detachLabel({ lix, entity, label: { id: important.id } });

Querying with labels

Use the ebEntity().hasLabel(...) helper to filter by labels.

import { ebEntity } from "@lix-js/sdk";

// Files labeled "important" (by label name)
const files = await lix.db
  .selectFrom("file")
  .where(ebEntity("file").hasLabel({ name: "important" }))
  .selectAll()
  .execute();

// Change sets labeled by a known label id
const urgent = await lix.db
  .selectFrom("label")
  .where("name", "=", "urgent")
  .selectAll()
  .executeTakeFirstOrThrow();

const changeSets = await lix.db
  .selectFrom("change_set")
  .where(ebEntity("change_set").hasLabel({ id: urgent.id }))
  .selectAll()
  .execute();

Advanced (SQL): Under the hood, labels live in label, and attachments in entity_label.

// All entities labeled "reviewed" (any schema)
const reviewedEntities = await lix.db
  .selectFrom("entity_label")
  .innerJoin("label", "label.id", "entity_label.label_id")
  .where("label.name", "=", "reviewed")
  .select([
    "entity_label.entity_id",
    "entity_label.schema_key",
    "entity_label.file_id",
  ])
  .execute();

Recommended naming

Labels have a single name field. Use a naming scheme that fits your workflow, for example:

• Simple tags: urgent, bug, reviewed, draft
• Namespaced tags: status:approved, type:feature, priority:high
• Milestones: checkpoint, release:v1.2.0

Special label uses

Checkpoint label

The createCheckpoint() helper converts the current working change set into a checkpoint and attaches the checkpoint label to the resulting checkpoint commit. This makes it easy to query and display checkpoints in history.

import { createCheckpoint } from "@lix-js/sdk";

// Create a checkpoint (adds the `checkpoint` label to the checkpoint commit)
await createCheckpoint({ lix });

Example: Workflow with labels

import { createChangeSet, createLabel, attachLabel } from "@lix-js/sdk";

// Create a change set and attach labels
const feature = await createChangeSet({ lix });

const typeFeature = await createLabel({ lix, name: "type:feature" });
const statusInProgress = await createLabel({ lix, name: "status:in-progress" });

await attachLabel({
  lix,
  entity: {
    entity_id: feature.id,
    schema_key: "lix_change_set",
    file_id: "lix",
  },
  label: { id: typeFeature.id },
});

await attachLabel({
  lix,
  entity: {
    entity_id: feature.id,
    schema_key: "lix_change_set",
    file_id: "lix",
  },
  label: { id: statusInProgress.id },
});

// Later, update status
const statusReview = await createLabel({ lix, name: "status:review" });
await attachLabel({
  lix,
  entity: {
    entity_id: feature.id,
    schema_key: "lix_change_set",
    file_id: "lix",
  },
  label: { id: statusReview.id },
});

API Reference quick-links

Function / Type	Purpose	Docs
attachLabel()	Attach a label to an entity	/api/functions/attachLabel
detachLabel()	Detach a label from an entity	/api/functions/detachLabel
createLabel()	Create a label	/api/functions/createLabel
ebEntity()	Query helper with hasLabel(...)	/api/functions/ebEntity