Dataset, Trace, and Span Renames

Version 5.0.0 renames three things you use every day. This page lists each old name, what to write instead, and the one case that needs a careful look.

The new names

Old name	New name	What it is
Test	Dataset	The collection of test cases you evaluate a version against
Trace	Span	One step your product took while answering: a tool call, a retrieval, a model call
Inference Result	Trace	One input and the output your product returned

Every level now has one word: a session holds traces, and a trace holds spans. Test Case keeps its name. Only the collection around it is now a dataset, so galtea.test_cases is unchanged.

Check your `traces` calls

galtea.traces used to mean what is now a span. It now means a trace. It is the one name that kept its spelling and changed what it points to.

If you used galtea.traces for steps, use galtea.spans instead:

You wrote	Now write
`galtea.traces.create(inference_result_id=..., name=...)`	`galtea.spans.create(trace_id=..., name=...)`
`galtea.traces.create_batch(traces=[TraceBase(inference_result_id=..., name=...)])`	`galtea.spans.create_batch(spans=[SpanBase(trace_id=..., name=...)])`
`galtea.traces.list(inference_result_id=...)`	`galtea.spans.list(trace_id=...)`
`galtea.traces.list(session_id=...)`	`galtea.spans.list(session_id=...)`
`galtea.traces.list(id=...)`	`galtea.spans.list(id=...)`
`galtea.traces.get(...)`	`galtea.spans.get(...)`
`galtea.traces.delete(...)`	`galtea.spans.delete(...)`

Only one of those calls stays quiet when you leave it unchanged. This is what each one does:

create and create_batch raise an error naming galtea.spans. Nothing is written.
create_batch(traces=[...]) and list(inference_result_id=...) raise a plain TypeError about an unexpected keyword argument. The error is correct but says nothing about spans.
list(session_id=...) is the one silent case. It returns the session’s traces where it used to return its spans, and reports no error. Search your code for it.
list(id=...), get(...) and delete(...) given the id of a span return a not-found error. Nothing is deleted. inference_result_id= is a supported alias on get and delete, so passing it does not fail either; the id is what fails.

What the new code looks like

A dataset list, a trace, a span inside that trace, and the spans of that trace:

# `galtea.datasets` replaces `galtea.tests`.
datasets = galtea.datasets.list(product_id=product_id)

# `galtea.traces` is one input paired with one output.
migrated_trace = galtea.traces.create(
    session_id=session_context.id,
    input="What is the refund window?",
    output="You can request a refund within 30 days.",
)
if migrated_trace is None:
    raise ValueError("migrated_trace is None")

# `galtea.spans` replaces the span-level `galtea.traces`.
migrated_span = galtea.spans.create(
    trace_id=migrated_trace.id,
    name="retrieve_policy_docs",
    type=SpanType.RETRIEVER,
    input_data={"query": "refund window"},
    output_data=["Refunds are accepted within 30 days."],
)

# `galtea.spans.create_batch(spans=...)` replaces `galtea.traces.create_batch(traces=...)`.
# The trace id moves onto each item; the method itself takes no id.
migrated_spans = galtea.spans.create_batch(
    spans=[
        SpanBase(trace_id=migrated_trace.id, name="rerank_documents", type=SpanType.TOOL),
        SpanBase(trace_id=migrated_trace.id, name="compose_answer", type=SpanType.GENERATION),
    ]
)

# `galtea.spans.list(trace_id=...)` replaces `galtea.traces.list(inference_result_id=...)`.
spans_of_trace = galtea.spans.list(trace_id=migrated_trace.id)

Names that keep working

These still work in 5.0.0. Each one prints a warning with the new name and the line to change. They are removed in a later release, so update them when you can. Accessors

Old	New
`galtea.tests`	`galtea.datasets`
`galtea.inference_results`	`galtea.traces`
`galtea.specifications.link_tests`, `unlink_tests`, `get_tests`	`link_datasets`, `unlink_datasets`, `get_datasets`

Classes you import

Old	New
`Test`, `TestStatus`, `TestType`	`Dataset`, `DatasetStatus`, `DatasetType`
`InferenceResult`, `InferenceResultStatus`, `InferenceResultUpdate`	`Trace`, `TraceStatus`, `TraceUpdate`

Tracing helpers

Old	New
`start_trace(...)`	`start_span(...)`
`@trace(...)`	`@traced(...)`
`get_inference_result_id()`	`get_trace_id()`
`flush_inference(...)`	`flush_trace(...)`

Your instrumented code keeps recording the same data through the old helpers, so you can rename them at your own pace. All of these are imported from galtea (from galtea import start_span) except the flush helpers, which live in galtea.infrastructure.telemetry.provider under both names. Arguments and fields

Old	New
`inference_result_id=`	`trace_id=`
`inference_results=`	`traces=`
`test_id=`	`dataset_id=`
`test_name=`	`dataset_name=`
`test=`	`dataset=`
`test_file_path=`	`dataset_file_path=`
`test_type=`, `test_variant=` on `galtea.specifications`	`dataset_type=`, `dataset_variant=`
`.inference_result_id`	`.trace_id`
`.test_id`	`.dataset_id`
`.parent_trace_id`	`.parent_span_id`

Two of those rows need a second look:

inference_results= is also in code you wrote yourself. A CustomScoreEvaluationMetric subclass declares it as a parameter of its own measure() method. Rename it in your subclass signature as well as at the call site. The SDK reads your signature and warns you if it still says inference_results.
galtea.metrics.create(test_type=...) is the exception to the test_type= row. There, the parameter was retired rather than renamed: it is no longer used to create a metric and there is no dataset_type= to move to. Delete the argument instead of renaming it.

Names that stop working

Old	New
`galtea.traces` for span operations	`galtea.spans`, see above
`galtea.traces.start_trace(...)`, `galtea.traces.trace(...)`	`galtea.spans.start_span(...)`, `galtea.spans.traced(...)`
`traces=` on `create_batch`	`spans=`, holding `SpanBase` items instead of `TraceBase` items
`TraceType`	`SpanType`
`TraceBase`	`SpanBase`

Names outside your Python code

Two more places carry the old names, and neither is Python. Both have a new spelling, and both still accept the old one. Endpoint Connection input templates. The placeholders you write in the template Galtea sends to your product:

Old	New
`{{ inference_result_id }}`	`{{ trace_id }}`
`{{ test_id }}`	`{{ dataset_id }}`

{{ test_case_id }} is unchanged, because Test Case keeps its name. OpenTelemetry span attributes. The attribute keys your own instrumentation sets when you export spans to Galtea:

Old	New
`galtea.inference_result.id`	`galtea.trace.id`
`galtea.trace.type`, `.description`, `.input`, `.output`, `.error`, `.metadata`	`galtea.span.type`, `.description`, `.input`, `.output`, `.error`, `.metadata`

If a span carries both names for the same field, the new name wins, unless it was sent with no value at all. You do not need to change anything for spans the SDK sends for you, through @traced, start_span, or set_context. The SDK still sends the old keys, and Galtea reads them.

Check your Galtea version before you change either of these. Both names are read by the Galtea API, not by the SDK, so a new name only works against an API that already knows it. Galtea Cloud already does. On a private or on-premise deployment, ask your account team first. Against an older API the new names fail quietly, in three different ways:

galtea.span.* fields are not recognised, so they land in the span’s metadata instead of in the fields they name.
galtea.trace.id does not link the span to its trace. The span is then treated as uncorrelated, so it is either assembled into a new production session or rejected.
{{ trace_id }} and {{ dataset_id }} are not known placeholders. Saving the connection fails validation, and a template that slips through renders an empty value.

The old names work on every version, so leaving them exactly as they are is always safe. If you are not sure which API version you are on, do not change them.

CLI commands

The CLI has no aliases. An old command fails with unknown command.

Old command	New command
`galtea inference-results <verb>`	`galtea traces <verb>`
`galtea tests <verb>`	`galtea datasets <verb>`
`galtea traces <verb>`, for spans	`galtea spans <verb>`
`galtea traces ingest-otel`	`galtea otel ingest`
`galtea traces otel-auth`	`galtea otel auth`
`galtea evaluations create-from-inference-result`	`galtea evaluations create-from-trace`
`galtea specifications link-tests`, `unlink-tests`, `list-tests`	`link-datasets`, `unlink-datasets`, `list-datasets`

Run galtea sync after upgrading, then galtea <noun> --help to see the verbs.

Staying on 4.x

Not ready to migrate the SDK? Pin it to the last version with the old names:

pip install "galtea<5"

Put that in requirements.txt or pyproject.toml, not only in one shell, because pip install -U galtea ignores a pin you never wrote down.

Pinning does not buy you time on the CLI. The CLI does not carry its command names in the binary. It reads them from the Galtea API’s own specification and refreshes that copy by itself, roughly once a day, without being asked. So galtea inference-results and galtea tests start failing once the API ships the renames, whatever CLI version you installed. Update your CLI call sites before you upgrade the SDK, and do not wait for a broken script to tell you. See CLI usage.

Checklist

Search for galtea.traces. Every hit is either a trace call that is already correct or a span call to move to galtea.spans. Check list, get and delete by hand, because those run either way.
Search for inference_result, test_ except test_case, galtea.tests, and the Test and InferenceResult class names. These keep working with a warning, so rename them when convenient.
Run your code once and read the warnings. Each one names the new spelling and the line to change.
On the CLI, swap galtea inference-results for galtea traces, galtea tests for galtea datasets, and any span usage of galtea traces for galtea spans.
Last, and only after checking your Galtea version, update the two names outside your Python code: the template placeholders and the OpenTelemetry attribute keys.

test_cases never changes. Test Case keeps its name, so leave galtea.test_cases, every test_case_id argument, and {{ test_case_id }} alone. Only the collection around a test case became a dataset. A search-and-replace of test across your code is the one thing on this page that can break something the SDK will not warn you about.

Getting Started

Core Workflows

Production & Monitoring

Advanced

Playbooks

Integrations

Security & Administration

Migration Guides

Dataset, Trace, and Span Renames

The new names

Check your `traces` calls

What the new code looks like

Names that keep working

Names that stop working

Names outside your Python code

CLI commands

Staying on 4.x

Checklist

​The new names

​Check your traces calls

​What the new code looks like

​Names that keep working

​Names that stop working

​Names outside your Python code

​CLI commands

​Staying on 4.x

​Checklist

The new names

Check your `traces` calls

What the new code looks like

Names that keep working

Names that stop working

Names outside your Python code

CLI commands

Staying on 4.x

Checklist