> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-docs-sandboxes-integrations-placement.mintlify.site/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 W&B Weave
This page explains how to publish, retrieve, delete, and reference versioned objects in W\&B 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={null}
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 lines theme={null}
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.
```typescript twoslash lines theme={null}
// @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.
`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={null}
weave.init("your-team-name/your-project-name")
cat_names = weave.ref('cat-names').get()
```
```plaintext lines theme={null}
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.
To delete a version of an object, call `.delete()` on the object's ref.
```python lines theme={null}
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.
```plaintext theme={null}
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={null}
weave:///[YOUR-TEAM-NAME]/[YOUR-PROJECT-NAME]/object/[OBJECT-NAME]:[OBJECT-VERSION]
```
* `[YOUR-TEAM-NAME]`: W\&B entity (username or team name)
* `[YOUR-PROJECT-NAME]`: W\&B 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`.
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={null}
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={null}
This feature is not available in the TypeScript SDK yet.
```