Track and version objects

This page explains how to publish, retrieve, delete, and reference versioned objects in Weave. Use it when you need to track structured data such as datasets, models, or prompts across runs and over time.

Objects

An Object is versioned, serializable data. Weave automatically versions objects when they change and creates an immutable history. Objects include:

Datasets: Collections of examples for evaluation
Models: Configurations and parameters for your LLM logic
Prompts: Versioned prompt templates

dataset = weave.Dataset(
    name="test-cases",
    rows=[
        {"input": "What is 2+2?", "expected": "4"},
        {"input": "What is the capital of France?", "expected": "Paris"},
    ]
)
weave.publish(dataset)

Publish an object

Weave’s serialization layer saves and versions objects.

Python
TypeScript

import weave
weave.init("your-team-name/your-project-name")
# Save a list, giving it the name 'cat-names'
weave.publish(['felix', 'jimbo', 'billie'], 'cat-names')

TypeScript publishing support is limited. Not all objects are supported.

import * as weave from 'weave'

const client = await weave.init("your-team-name/your-project-name")

// Save an array, giving it the name 'cat-names'
client.publish(['felix', 'jimbo', 'billie'], 'cat-names')

When you save an object with a name, Weave creates the first version of that object if it doesn’t exist.

Get an object back

After publishing, you can fetch a stored object using its reference.

Python
TypeScript

weave.publish() returns a Ref. Call .get() on any Ref to get the object back.You can construct a ref and then fetch the object back.

weave.init("your-team-name/your-project-name")
cat_names = weave.ref('cat-names').get()

This feature isn't available in TypeScript yet.

Delete an object

If you no longer need a specific version of an object, you can remove it using its ref.

Python
TypeScript

To delete a version of an object, call .delete() on the object’s ref.

weave.init("your-team-name/your-project-name")
cat_names_ref = weave.ref('cat-names:v1')
cat_names_ref.delete()

Accessing a deleted object returns an error. Resolving an object that references a deleted object returns a DeletedRef in place of the deleted object.

This feature isn't available in TypeScript yet.

Construct object refs

Refs uniquely identify a stored object and version. The following sections describe the URI structure and the ways you can construct a ref. In Weave, a fully qualified object ref URI looks like this:

weave:///[YOUR-TEAM-NAME]/[YOUR-PROJECT-NAME]/object/[OBJECT-NAME]:[OBJECT-VERSION]

[YOUR-TEAM-NAME]: Weights & Biases entity (username or team name)
[YOUR-PROJECT-NAME]: Weights & Biases project
[OBJECT-NAME]: object name
[OBJECT-VERSION]: either a version hash, a string like v0 or v1, or an alias like :latest. All objects have the :latest alias. See Organize object versions with tags and aliases to create your own aliases.

You can construct refs with a few different styles:

weave.ref([NAME]): retrieves the :latest version of an object. Requires calling weave.init(...).
weave.ref([NAME]:[VERSION]): retrieves the specified version of an object. Requires calling weave.init(...).
weave.ref([FULLY-QUALIFIED-REF-URI]): retrieves the object located at the specified fully qualified object ref URI. Doesn’t require calling weave.init().

Organize object versions with tags and aliases

Use tags and aliases to label specific versions of any Weave object, including Dataset, Model, Prompt, or any other object you publish with weave.publish. These labels work on any ObjectRef, so the same APIs apply across object types.

Alias: A unique name that resolves to a single version. You can move an alias to a different version at any time, making it useful for stable references like production or staging. Every object automatically has a :latest alias that points to the most recent version.
Tag: A descriptive label attached to a version. A version can have multiple tags, and the same tag can appear on multiple versions. Use tags to categorize and filter versions, such as reviewed or passed-eval.

For the characters and lengths that tags and aliases accept, see Naming rules. Resolve an alias or specific version by appending it to the object name in a ref: The following example publishes two versions of a dataset, then assigns and updates tags and aliases on each version.

import weave

client = weave.init("[YOUR-TEAM-NAME]/[YOUR-PROJECT-NAME]")

# Publish two versions of an object.
dataset_v0 = weave.publish(
    weave.Dataset(name="test-cases", rows=[{"input": "ping", "expected": "pong"}]),
)
dataset_v1 = weave.publish(
    weave.Dataset(name="test-cases", rows=[{"input": "ping", "expected": "pong!"}]),
)

# Set aliases at a version.
client.set_aliases(dataset_v0, "staging")
client.set_aliases(dataset_v1, "production")

# Retrieve an object using its alias
dataset = weave.ref("test-cases:production").get()

# List all aliases in the project.
client.list_aliases()

# --- Tags: labels on a specific version. ---

# Add tags to a version.
client.add_tags(dataset_v0, ["reviewed", "passed-eval"])
client.add_tags(dataset_v1, ["reviewed", "needs-improvement"])

# Get tags for a version.
client.get_tags(dataset_v0)  # ["passed-eval", "reviewed"]

# List all distinct tags in the project.
client.list_tags()

This feature is not available in the TypeScript SDK yet.

Naming rules

Object names, tags, and aliases must follow these rules. Weave rejects a tag or alias that breaks them.

Name	Length	Allowed characters	Other rules
Object name	1 to 128 characters	Letters, numbers, underscores (`_`), periods (`.`), and hyphens (`-`)	None
Tag	1 to 256 characters	Letters, numbers, underscores (`_`), hyphens (`-`), and spaces	Spaces can appear only between words, one at a time. A tag can’t start or end with a space.
Alias	1 to 128 characters	Any character except `/` and `:`	Can’t be only whitespace. `latest` and version names, such as `v0` or `v12`, are reserved because refs use them to select versions.

Before publishing an object, the Python SDK checks its name against the following rules and rewrites it as necessary:

Replaces each run of characters other than letters, numbers, underscores, and periods with a single hyphen.
Replaces each run of two or more periods, underscores, or hyphens with a single hyphen.
Removes hyphens and underscores from the start and end of the name.
If the name is still longer than 128 characters, keeps the first 128 and logs a warning.

If nothing is left after the rewrite, weave.publish() raises a ValueError. The ref that weave.publish() returns carries the rewritten name, so use that name to get the object back: The TypeScript SDK doesn’t rewrite a name that you pass to client.publish(). If the name breaks the object name rules, the request fails. For Op name and Call display name limits, see Name length limits.

Weights & Biases

Guides

Integrations

Reference

Support

Objects

Publish an object

Get an object back

Delete an object

Construct object refs

Organize object versions with tags and aliases

Naming rules

​Objects

​Publish an object

​Get an object back

​Delete an object

​Construct object refs

​Organize object versions with tags and aliases

​Naming rules

Objects

Publish an object

Get an object back

Delete an object

Construct object refs

Organize object versions with tags and aliases

Naming rules