> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Track and version objects

> Track and version any JSON-serializable object in Weave

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

```python lines theme={"system"}
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.

> [tab] Python
>
> ```python lines theme={"system"}
> 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')
> ```

> [tab] TypeScript
>
> TypeScript publishing support is limited. Not all objects are supported.
>
> ```typescript twoslash lines theme={"system"}
> // @noErrors
> 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.

> [tab] Python
>
> `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.
>
> ```python lines theme={"system"}
> weave.init("your-team-name/your-project-name")
> cat_names = weave.ref('cat-names').get()
> ```

> [tab] TypeScript
>
> ```plaintext lines theme={"system"}
> 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.

> [tab] Python
>
> To delete a version of an object, call `.delete()` on the object's ref.
>
> ```python lines theme={"system"}
> 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.

> [tab] TypeScript
>
> ```plaintext theme={"system"}
> 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:

```text theme={"system"}
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](#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](#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.

```python Python lines theme={"system"}
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()
```

```plaintext TypeScript lines theme={"system"}
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:

1. Replaces each run of characters other than letters, numbers, underscores, and periods with a single hyphen.
2. Replaces each run of two or more periods, underscores, or hyphens with a single hyphen.
3. Removes hyphens and underscores from the start and end of the name.
4. 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](https://docs.coreweave.com/products/wandb/weave/guides/tracking/set-call-display.md#name-length-limits).
