Skip to main content
Version: 2.21-unstable

Data Classes

In Haystack, there are a handful of core classes that are regularly used in many different places. These are classes that carry data through the system and you are likely to interact with these as either the input or output of your pipeline.

Haystack uses data classes to help components communicate with each other in a simple and modular way. By doing this, data flows seamlessly through the Haystack pipelines. This page goes over the available data classes in Haystack: ByteStream, Answer (along with its variants ExtractedAnswer and GeneratedAnswer), ChatMessage, Document, and StreamingChunk, explaining how they contribute to the Haystack ecosystem.

You can check out the detailed parameters in our Data Classes API reference.

Answer​

Overview​

The Answer class serves as the base for responses generated within Haystack, containing the answer's data, the originating query, and additional metadata.

Key Features​

  • Adaptable data handling, accommodating any data type (data).
  • Query tracking for contextual relevance (query).
  • Extensive metadata support for detailed answer description.

Attributes​

python
@dataclass
class Answer:
    data: Any
    query: str
    meta: Dict[str, Any]

ExtractedAnswer​

Overview​

ExtractedAnswer is a subclass of Answer that deals explicitly with answers derived from Documents, offering more detailed attributes.

Key Features​

  • Includes reference to the originating Document.
  • Score attribute to quantify the answer's confidence level.
  • Optional start and end indices for pinpointing answer location within the source.

Attributes​

python
@dataclass
class ExtractedAnswer:
    query: str
    score: float
    data: Optional[str] = None
    document: Optional[Document] = None
    context: Optional[str] = None
    document_offset: Optional["Span"] = None
    context_offset: Optional["Span"] = None
    meta: Dict[str, Any] = field(default_factory=dict)

GeneratedAnswer​

Overview​

GeneratedAnswer extends the Answer class to accommodate answers generated from multiple Documents.

Key Features​

  • Handles string-type data.
  • Links to a list of Document objects, enhancing answer traceability.

Attributes​

python
@dataclass
class GeneratedAnswer:
    data: str
    query: str
    documents: List[Document]
    meta: Dict[str, Any] = field(default_factory=dict)

ByteStream​

Overview​

ByteStream represents binary object abstraction in the Haystack framework and is crucial for handling various binary data formats.

Key Features​

  • Holds binary data and associated metadata.
  • Optional MIME type specification for flexibility.
  • File interaction methods (to_file, from_file_path, from_string) for easy data manipulation.

Attributes​

python
@dataclass(repr=False)
class ByteStream:
    data: bytes
    meta: Dict[str, Any] = field(default_factory=dict, hash=False)
    mime_type: Optional[str] = field(default=None)

Example​

python
from haystack.dataclasses.byte_stream import ByteStream

image = ByteStream.from_file_path("dog.jpg")

ChatMessage​

ChatMessage is the central abstraction to represent a message for a LLM. It contains role, metadata and several types of content, including text, tool calls and tool calls results.

Read the detailed documentation for the ChatMessage data class on a dedicated ChatMessage page.

Document​

Overview​

Document represents a central data abstraction in Haystack, capable of holding text, tables, and binary data.

Key Features​

  • Unique ID for each document.
  • Multiple content types are supported: text, binary (blob).
  • Custom metadata and scoring for advanced document management.
  • Optional embedding for AI-based applications.

Attributes​

python
@dataclass
class Document(metaclass=_BackwardCompatible):
    id: str = field(default="")
    content: Optional[str] = field(default=None)
    blob: Optional[ByteStream] = field(default=None)
    meta: Dict[str, Any] = field(default_factory=dict)
    score: Optional[float] = field(default=None)
    embedding: Optional[List[float]] = field(default=None)
    sparse_embedding: Optional[SparseEmbedding] = field(default=None)

Example​

python
from haystack import Document

documents = Document(content="Here are the contents of your document", embedding=[0.1]*768)

StreamingChunk​

Overview​

StreamingChunk represents a partially streamed LLM response, enabling real-time LLM response processing. It encapsulates a segment of streamed content along with associated metadata and provides comprehensive information about the streaming state.

Key Features​

  • String-based content representation for text chunks
  • Support for tool calls and tool call results
  • Component tracking and metadata management
  • Streaming state indicators (start, finish reason)
  • Content block indexing for multi-part responses

Attributes​

python
@dataclass
class StreamingChunk:
    content: str
    meta: dict[str, Any] = field(default_factory=dict, hash=False)
    component_info: Optional[ComponentInfo] = field(default=None)
    index: Optional[int] = field(default=None)
    tool_calls: Optional[list[ToolCallDelta]] = field(default=None)
    tool_call_result: Optional[ToolCallResult] = field(default=None)
    start: bool = field(default=False)
    finish_reason: Optional[FinishReason] = field(default=None)
    reasoning: Optional[ReasoningContent] = field(default=None)

Example​

python
from haystack.dataclasses import StreamingChunk, ToolCallDelta, ReasoningContent

## Basic text chunk
chunk = StreamingChunk(
    content="Hello world",
    start=True,
    meta={"model": "gpt-3.5-turbo"}
)

## Tool call chunk
tool_chunk = StreamingChunk(
    content="",
    tool_calls=[ToolCallDelta(index=0, tool_name="calculator", arguments='{"operation": "add", "a": 2, "b": 3}')],
    index=0,
    start=False,
    finish_reason="tool_calls"
)

## Reasoning chunk
reasoning_chunk = StreamingChunk(
    content="",
    reasoning=ReasoningContent(reasoning_text="Thinking step by step about the answer."),
    index=0,
    start=True,
    meta={"model": "gpt-4.1-mini"}
)

ToolCallDelta​

Overview​

ToolCallDelta represents a tool call prepared by the model, usually contained in an assistant message during streaming.

Attributes​

python
@dataclass
class ToolCallDelta:
    index: int
    tool_name: Optional[str] = field(default=None)
    arguments: Optional[str] = field(default=None)
    id: Optional[str] = field(default=None)
    extra: Optional[Dict[str, Any]] = field(default=None)

ComponentInfo​

Overview​

The ComponentInfo class represents information about a component within a Haystack pipeline. It is used to track the type and name of components that generate or process data, aiding in debugging, tracing, and metadata management throughout the pipeline.

Key Features​

  • Stores the type of the component (including module and class name).
  • Optionally stores the name assigned to the component in the pipeline.
  • Provides a convenient class method to create a ComponentInfo instance from a Component object.

Attributes​

python
@dataclass
class ComponentInfo:
    type: str
    name: Optional[str] = field(default=None)

    @classmethod
    def from_component(cls, component: Component) -> "ComponentInfo":
        ...

Example​

python
from haystack.dataclasses.streaming_chunk import ComponentInfo
from haystack.core.component import Component

class MyComponent(Component):
    ...

component = MyComponent()
info = ComponentInfo.from_component(component)
print(info.type)  # e.g., 'my_module.MyComponent'
print(info.name)  # Name assigned in the pipeline, if any

SparseEmbedding​

Overview​

The SparseEmbedding class represents a sparse embedding: a vector where most values are zeros.

Attributes​

  • indices: List of indices of non-zero elements in the embedding.
  • values: List of values of non-zero elements in the embedding.

Tool​

Tool is a data class representing a tool that Language Models can prepare a call for.

Read the detailed documentation for the Tool data class on a dedicated Tool page.