Export Data & Query Spans

Options for Exporting Data from Phoenix

Method	Description	Helpful for
Download all spans as a dataframe	Exports all spans in a project as a dataframe	Evaluation - Filtering your spans locally using pandas instead of Phoenix DSL.
Span Queries	Exports specific spans or traces based on filters	Evaluation - Querying spans from Phoenix

Connect to Phoenix

Point your code at the Phoenix instance you started. The endpoint below is the default for a local phoenix serve; for a deployment running elsewhere, use its hostname instead.

import os

os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = "http://localhost:6006"

# Only if the deployment has authentication enabled
# os.environ["PHOENIX_API_KEY"] = "your-api-key"

from phoenix.client import Client

client = Client()

Downloading all Spans as a Dataframe

If you prefer to handle your filtering locally, you can also download all spans as a dataframe using the get_spans_dataframe() method:

from phoenix.client import Client

client = Client()

# Download all spans from your default project
client.spans.get_spans_dataframe()

# Download all spans from a specific project
client.spans.get_spans_dataframe(project_name='your project name')

Running Span Queries

You can query for data using our query DSL (domain specific language).

The .where() filter expression is the same language used by the filter bar in the dashboard — see the Filter Expressions reference for the full language. It can be helpful to form your filter in the Phoenix dashboard for more immediate feedback, before moving it to code.

Below is an example of how to pull all retriever spans and select the input value. The output of this query is a DataFrame that contains the input values for all retriever spans.

from phoenix.client import Client
from phoenix.trace.dsl import SpanQuery

client = Client()

query = SpanQuery().where(
    # Filter for the `RETRIEVER` span kind.
    # The filter condition is a string of valid Python boolean expression.
    "span_kind == 'RETRIEVER'",
).select(
    # Extract the span attribute `input.value` which contains the query for the
    # retriever. Rename it as the `input` column in the output dataframe.
    input="input.value",
)

# The Phoenix Client can take this query and return the dataframe.
client.spans.get_spans_dataframe(query=query)

DataFrame Index By default, the result DataFrame is indexed by span_id, and if .explode() is used, the index from the exploded list is added to create a multi-index on the result DataFrame. For the special retrieval.documents span attribute, the added index is renamed as document_position.

How to Specify a Time Range

By default, all queries will collect all spans that are in your Phoenix instance. If you’d like to focus on most recent spans, you can pull spans based on time frames using start_time and end_time.

from phoenix.client import Client
from phoenix.trace.dsl import SpanQuery
from datetime import datetime, timedelta

client = Client()

# Get spans from the last 7 days only
start = datetime.now() - timedelta(days=7)

# Get spans to exclude the last 24 hours
end = datetime.now() - timedelta(days=1)

phoenix_df = client.spans.get_spans_dataframe(start_time=start, end_time=end)

How to Specify a Project

By default all queries are executed against the default project or the project set via the PHOENIX_PROJECT_NAME environment variable. If you choose to pull from a different project, all methods on the Client have an optional parameter named project_name

from phoenix.client import Client
from phoenix.trace.dsl import SpanQuery

client = Client()

# Get spans from a project
client.spans.get_spans_dataframe(project_name="<my-project>")

# Using the query DSL
query = SpanQuery().where("span_kind == 'CHAIN'").select(input="input.value")
client.spans.get_spans_dataframe(query=query, project_name="<my-project>")

Querying for Retrieved Documents

Let’s say we want to extract the retrieved documents into a DataFrame that looks something like the table below, where input denotes the query for the retriever, reference denotes the content of each document, and document_position denotes the (zero-based) index in each span’s list of retrieved documents. Note that this DataFrame can be used directly as input for the Retrieval (RAG) Relevance evaluations.

context.span_id	document_position	input	reference
5B8EF798A381	0	What was the author’s motivation for writing …	In fact, I decided to write a book about …
5B8EF798A381	1	What was the author’s motivation for writing …	I started writing essays again, and wrote a bunch of …
…	…	…	…
E19B7EC3GG02	0	What did the author learn about …	The good part was that I got paid huge amounts of …

We can accomplish this with a simple query as follows:

from phoenix.client import Client
from phoenix.trace.dsl import SpanQuery

client = Client()

query = SpanQuery().where(
    # Filter for the `RETRIEVER` span kind.
    # The filter condition is a string of valid Python boolean expression.
    "span_kind == 'RETRIEVER'",
).select(
    # Extract the span attribute `input.value` which contains the query for the
    # retriever. Rename it as the `input` column in the output dataframe.
    input="input.value",
).explode(
    # Specify the span attribute `retrieval.documents` which contains a list of
    # objects and explode the list. Extract the `document.content` attribute from
    # each object and rename it as the `reference` column in the output dataframe.
    "retrieval.documents",
    reference="document.content",
)

# The Phoenix Client can take this query and return the dataframe.
client.spans.get_spans_dataframe(query=query)

How to Explode Attributes

In addition to the document content, if we also want to explode the document score, we can simply add the document.score attribute to the .explode() method alongside document.content as follows. Keyword arguments are necessary to name the output columns, and in this example we name the output columns as reference and score. (Python’s double-asterisk unpacking idiom can be used to specify arbitrary output names containing spaces or symbols. See here for an example.)

query = SpanQuery().explode(
    "retrieval.documents",
    reference="document.content",
    score="document.score",
)

How to Apply Filters

The .where() method accepts a filter expression — a string of valid Python boolean expression — and returns only the spans it matches. The same expressions work in the spans/traces filter bar in the Phoenix UI.

query = SpanQuery().where(
    "span_kind == 'RETRIEVER' and 'programming' in input.value"
)

The filter expression language — attribute and annotation access, substring search, is None, and the full operator set — is documented in one place, for both spans and sessions:

Filter Expressions

The span and session filter language: fields, attributes, annotations/evals, substring search, is None, and more.

How to Extract Attributes

Span attributes can be selected by simply listing them inside .select() method.

query = SpanQuery().select(
    "input.value",
    "output.value",
)

Renaming Output Columns

Keyword-argument style can be used to rename the columns in the dataframe. The example below returns two columns named input and output instead of the original names of the attributes.

query = SpanQuery().select(
    input="input.value",
    output="output.value",
)

Arbitrary Output Column Names

If arbitrary output names are desired, e.g. names with spaces and symbols, we can leverage Python’s double-asterisk idiom for unpacking a dictionary, as shown below.

query = SpanQuery().select(**{
    "Value (Input)": "input.value",
    "Value (Output)": "output.value",
})

Advanced Usage

Concatenating

The document contents can also be concatenated together. The query below concatenates the list of document.content with (double newlines), which is the default separator. Keyword arguments are necessary to name the output columns, and in this example we name the output column as reference. (Python’s double-asterisk unpacking idiom can be used to specify arbitrary output names containing spaces or symbols. See here for an example.)

query = SpanQuery().concat(
    "retrieval.documents",
    reference="document.content",
)

Special Separators

If a different separator is desired, say \n************, it can be specified as follows.

query = SpanQuery().concat(
    "retrieval.documents",
    reference="document.content",
).with_concat_separator(
    separator="\n************\n",
)

Using Parent ID as Index

This is useful for joining a span to its parent span. To do that we would first index the child span by selecting its parent ID and renaming it as span_id. This works because span_id is a special column name: whichever column having that name will become the index of the output DataFrame.

query = SpanQuery().select(
    span_id="parent_id",
    output="output.value",
)

Joining a Span to Its Parent

To do this, provide two queries to Phoenix and join the resulting dataframes with pandas.

import pandas as pd
from phoenix.client import Client
from phoenix.trace.dsl import SpanQuery

client = Client()

parent_df = client.spans.get_spans_dataframe(query=query_for_parent_spans)
child_df = client.spans.get_spans_dataframe(query=query_for_child_spans)

pd.concat(
    [parent_df, child_df],
    axis=1,        # joining on the row indices
    join="inner",  # inner-join by the indices of the dataframes
)

How to use Data for Evaluation

Extract the Input and Output from LLM Spans

To learn more about extracting span attributes, see How to Extract Attributes.

from phoenix.client import Client
from phoenix.trace.dsl import SpanQuery

client = Client()

query = SpanQuery().where(
    "span_kind == 'LLM'",
).select(
    input="input.value",
    output="output.value",
)

# The Phoenix Client can take this query and return a dataframe.
client.spans.get_spans_dataframe(query=query)

Retrieval (RAG) Relevance Evaluations

To extract the dataframe input for Retrieval (RAG) Relevance evaluations, apply the query described in Querying for Retrieved Documents.

Q&A on Retrieved Data Evaluations

To extract the dataframe input to the Q&A on Retrieved Data evaluations, use the following query which applies techniques described in the Advanced Usage section.

import pandas as pd
from phoenix.client import Client
from phoenix.trace.dsl import SpanQuery

client = Client()

query_for_root_span = SpanQuery().where(
    "parent_id is None",   # Filter for root spans
).select(
    input="input.value",   # Input contains the user's question
    output="output.value", # Output contains the LLM's answer
)

query_for_retrieved_documents = SpanQuery().where(
    "span_kind == 'RETRIEVER'",  # Filter for RETRIEVER span
).select(
    # Rename parent_id as span_id. This turns the parent_id
    # values into the index of the output dataframe.
    span_id="parent_id",
).concat(
    "retrieval.documents",
    reference="document.content",
)

root_df = client.spans.get_spans_dataframe(query=query_for_root_span)
docs_df = client.spans.get_spans_dataframe(query=query_for_retrieved_documents)

# Perform an inner join on the two sets of spans.
pd.concat(
    [root_df, docs_df],
    axis=1,
    join="inner",
)

The output DataFrame would look something like the one below. The input contains the question, the output column contains the answer, and the reference column contains a concatenation of all the retrieved documents.

context.span_id	input	output	reference
CDBC4CE34	What was the author’s trick for …	The author’s trick for …	Even then it took me several years to understand …
…	…	…	…

Get Started

Tracing

Evaluation

Datasets & Experiments

Prompts

Settings

Concepts

Resources

Export Data & Query Spans

Options for Exporting Data from Phoenix

Connect to Phoenix

Downloading all Spans as a Dataframe

Running Span Queries

How to Specify a Time Range

How to Specify a Project

Querying for Retrieved Documents

How to Explode Attributes

How to Apply Filters

Filter Expressions

How to Extract Attributes

Renaming Output Columns

Arbitrary Output Column Names

Advanced Usage

Concatenating

Special Separators

Using Parent ID as Index

Joining a Span to Its Parent

How to use Data for Evaluation

Extract the Input and Output from LLM Spans

Retrieval (RAG) Relevance Evaluations

Q&A on Retrieved Data Evaluations

​Options for Exporting Data from Phoenix

​Connect to Phoenix

​Downloading all Spans as a Dataframe

​Running Span Queries

​How to Specify a Time Range

​How to Specify a Project

​Querying for Retrieved Documents

​How to Explode Attributes

​How to Apply Filters

Filter Expressions

​How to Extract Attributes

​Renaming Output Columns

​Arbitrary Output Column Names

​Advanced Usage

​Concatenating

​Special Separators

​Using Parent ID as Index

​Joining a Span to Its Parent

​How to use Data for Evaluation

​Extract the Input and Output from LLM Spans

​Retrieval (RAG) Relevance Evaluations

​Q&A on Retrieved Data Evaluations

Options for Exporting Data from Phoenix

Connect to Phoenix

Downloading all Spans as a Dataframe

Running Span Queries

How to Specify a Time Range

How to Specify a Project

Querying for Retrieved Documents

How to Explode Attributes

How to Apply Filters

How to Extract Attributes

Renaming Output Columns

Arbitrary Output Column Names

Advanced Usage

Concatenating

Special Separators

Using Parent ID as Index

Joining a Span to Its Parent

How to use Data for Evaluation

Extract the Input and Output from LLM Spans

Retrieval (RAG) Relevance Evaluations

Q&A on Retrieved Data Evaluations