Implementation:Apache Airflow XComModel Operations

Knowledge Sources	Apache Airflow
Domains	Data_Engineering, ORM
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for inter-task data exchange provided by the Airflow XCom model.

Description

The XComModel class is a SQLAlchemy model that manages the xcom table. It provides class methods for setting, getting, and clearing XCom values. Values are stored as JSON (with PostgreSQL JSONB variant for better performance). The model supports mapped tasks via the map_index field.

Usage

Used internally by the Airflow execution engine to manage inter-task communication. Direct usage is through xcom_push/xcom_pull on TaskInstance or implicitly through TaskFlow API return values.

Code Reference

Source Location

Repository: Apache Airflow
File: airflow-core/src/airflow/models/xcom.py
Lines: L60-419

Signature

class XComModel(TaskInstanceDependencies):
    __tablename__ = "xcom"

    dag_run_id: Mapped[int]       # Primary key component
    task_id: Mapped[str]          # Primary key component
    map_index: Mapped[int]        # Primary key component (default -1)
    key: Mapped[str]              # Primary key component
    dag_id: Mapped[str]           # Denormalized for lookup
    run_id: Mapped[str]           # Denormalized for lookup
    value: Mapped[Any]            # JSON / PostgreSQL JSONB
    timestamp: Mapped[datetime]   # Auto-set to utcnow

    @classmethod
    def set(
        cls,
        key: str,
        value: Any,
        *,
        dag_id: str,
        task_id: str,
        run_id: str,
        map_index: int = -1,
        session: Session,
    ) -> None: ...

    @classmethod
    def clear(
        cls,
        *,
        dag_id: str,
        task_id: str,
        run_id: str,
        map_index: int | None = None,
        session: Session,
    ) -> None: ...

Import

from airflow.models.xcom import XComModel

I/O Contract

Inputs

Name	Type	Required	Description
key	str	Yes	XCom key name (max 512 chars)
value	Any	Yes	JSON-serializable data
dag_id	str	Yes	DAG identifier
task_id	str	Yes	Task identifier
run_id	str	Yes	DAG run identifier
map_index	int	No	Mapped task index (default -1)

Outputs

Name	Type	Description
Stored value	JSON row	Persisted in xcom table
Retrieved value	Any	Deserialized JSON value from xcom_pull

Usage Examples

Explicit XCom Push/Pull

# In an operator's execute method
def execute(self, context):
    # Push a value
    context["ti"].xcom_push(key="result", value={"count": 42})

    # Pull a value from upstream
    upstream_result = context["ti"].xcom_pull(
        task_ids="upstream_task",
        key="result"
    )

Related Pages

Implements Principle

Principle:Apache_Airflow_Task_Communication

Requires Environment

Uses Heuristic

Heuristic:Apache_Airflow_Memory_Management_Tips

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment