add.to()¶
Bring columns from one DataFrame into another by matching on a key column — the core lookup operation in additory.
Try the Shuffle button
Click 🔀 Shuffle to see every example rewritten for a different domain — healthcare, finance, retail, and more. The code pattern stays the same; only the data changes.
Simple Example¶
<code class="language-python" data-shuffle-template="import additory as add
import polars as pl
{{target.name}} = pl.DataFrame({ '{{target.columns.id}}': [{{target.rows[0].id}}, {{target.rows[1].id}}, {{target.rows[2].id}}], '{{target.columns.key}}': [{{target.rows[0].key}}, {{target.rows[1].key}}, {{target.rows[2].key}}], '{{target.columns.value1}}': ['{{target.rows[0].value1}}', '{{target.rows[1].value1}}', '{{target.rows[2].value1}}'], })
{{reference.name}} = pl.DataFrame({ '{{reference.columns.key}}': [{{reference.rows[0].key}}, {{reference.rows[1].key}}, {{reference.rows[2].key}}], '{{reference.columns.lookup1}}': ['{{reference.rows[0].lookup1}}', '{{reference.rows[1].lookup1}}', '{{reference.rows[2].lookup1}}'], '{{reference.columns.lookup2}}': ['{{reference.rows[0].lookup2}}', '{{reference.rows[1].lookup2}}', '{{reference.rows[2].lookup2}}'], })
result = add.to({{target.name}}, {{reference.name}}, '{{reference.columns.lookup1}}', '{{target.columns.key}}') print(result)">import additory as add import polars as pl
patients = pl.DataFrame({ 'patient_id': [1001, 1002, 1003], 'doctor_id': [201, 202, 203], 'diagnosis': ['Hypertension', 'Fracture', 'Asthma'], })
doctors = pl.DataFrame({ 'doctor_id': [201, 202, 203], 'name': ['Dr. Priya Sharma', 'Dr. Kenji Tanaka', 'Dr. Amara Osei'], 'specialty': ['Cardiology', 'Orthopedics', 'Pulmonology'], })
result = add.to(patients, doctors, 'name', 'doctor_id') print(result)
<code class="language-python" data-shuffle-template="import additory as add
import pandas as pd
{{target.name}} = pd.DataFrame({ '{{target.columns.id}}': [{{target.rows[0].id}}, {{target.rows[1].id}}, {{target.rows[2].id}}], '{{target.columns.key}}': [{{target.rows[0].key}}, {{target.rows[1].key}}, {{target.rows[2].key}}], '{{target.columns.value1}}': ['{{target.rows[0].value1}}', '{{target.rows[1].value1}}', '{{target.rows[2].value1}}'], })
{{reference.name}} = pd.DataFrame({ '{{reference.columns.key}}': [{{reference.rows[0].key}}, {{reference.rows[1].key}}, {{reference.rows[2].key}}], '{{reference.columns.lookup1}}': ['{{reference.rows[0].lookup1}}', '{{reference.rows[1].lookup1}}', '{{reference.rows[2].lookup1}}'], '{{reference.columns.lookup2}}': ['{{reference.rows[0].lookup2}}', '{{reference.rows[1].lookup2}}', '{{reference.rows[2].lookup2}}'], })
result = add.to({{target.name}}, {{reference.name}}, '{{reference.columns.lookup1}}', '{{target.columns.key}}') print(result)">import additory as add import pandas as pd
patients = pd.DataFrame({ 'patient_id': [1001, 1002, 1003], 'doctor_id': [201, 202, 203], 'diagnosis': ['Hypertension', 'Fracture', 'Asthma'], })
doctors = pd.DataFrame({ 'doctor_id': [201, 202, 203], 'name': ['Dr. Priya Sharma', 'Dr. Kenji Tanaka', 'Dr. Amara Osei'], 'specialty': ['Cardiology', 'Orthopedics', 'Pulmonology'], })
result = add.to(patients, doctors, 'name', 'doctor_id') print(result)
The four positional arguments map to a natural sentence: bring to this target, from this reference, bring these columns, matched against this key.
Parameters¶
| Parameter | Type | Default | Description |
|---|---|---|---|
bring_to | DataFrame or list[DataFrame] | (required) | Target DataFrame(s) to add columns to |
bring_from | DataFrame or list[DataFrame] | (required) | Reference DataFrame(s) to look up from |
bring | str or list[str] | (required) | Column name(s) to bring from the reference |
against | str or list[str] | (required) | Key column(s) to match on |
position | str or int | None | Where to place new columns: 'start', 'end', 'after:col', 'before:col', or integer index |
strategy | dict | None | Column-level aggregation strategies (e.g., {'amount': 'sum'}) |
join_type | str | 'lookup' | Join type: 'lookup', 'left', 'inner', 'outer' |
logging | bool | False | Enable detailed operation logging |
lineage | bool | False | Enable lineage tracking |
as_type | str | None | Force output type: 'pandas' or 'polars' |
Signature
Join Types¶
The join_type parameter controls how rows are matched:
| Join Type | Behaviour |
|---|---|
'lookup' | Default. Brings columns from the reference where keys match. Unmatched rows in the target keep null values. |
'left' | Standard left join — all target rows preserved. |
'inner' | Only rows with matching keys in both DataFrames. |
'outer' | All rows from both DataFrames, with null where no match exists. |
# Inner join — only matched rows
result = add.to(patients, doctors, 'name', 'doctor_id', join_type='inner')
Aggregation Strategies¶
When the reference has multiple rows per key, use strategy to control how values are combined:
Available aggregation strategies:
| Strategy | Description |
|---|---|
'sum' | Sum of values |
'count' | Count of values |
'average' | Mean of values |
'min' | Minimum value |
'max' | Maximum value |
'concat' | Concatenate text values |
'most_common' | Most frequent value |
'least_common' | Least frequent value |
'median' | Median value |
'std' | Standard deviation |
'variance' | Variance |
'unique_count' | Count of distinct values |
List-of-DataFrames Patterns¶
add.to() supports passing lists of DataFrames for batch operations:
# One-to-many: single target, multiple references
result = add.to(
customers,
[orders_jan, orders_feb, orders_mar],
'amount',
'customer_id',
strategy={'amount': 'sum'},
)
# Many-to-one: multiple targets, single reference
results = add.to(
[customers_a, customers_b],
products,
'product_name',
'product_id',
)
# results is a list of DataFrames
When bring_from is a list, the references are concatenated vertically before the lookup. When bring_to is a list, each target is processed independently and a list of results is returned.
Column Positioning¶
Control where new columns appear in the result:
# Place at the start
result = add.to(df, ref, 'name', 'id', position='start')
# Place after a specific column
result = add.to(df, ref, 'name', 'id', position='after:email')
# Place before a specific column
result = add.to(df, ref, 'name', 'id', position='before:status')
# Place at a specific index
result = add.to(df, ref, 'name', 'id', position=2)
Pipe Compatibility¶
add.to() is pipe-friendly — the first argument (bring_to) receives the DataFrame:
This works with method chaining:
result = (
patients
.pipe(add.to, doctors, 'name', 'doctor_id')
.pipe(add.to, departments, 'dept_name', 'dept_id')
)
Practical Scenarios¶
Bringing multiple columns¶
<code class="language-python" data-shuffle-template="result = add.to(
{{target.name}},
{{reference.name}},
['{{reference.columns.lookup1}}', '{{reference.columns.lookup2}}'],
'{{target.columns.key}}',
) print(result)">result = add.to( patients, doctors, ['name', 'specialty'], 'doctor_id', ) print(result)
<code class="language-python" data-shuffle-template="result = add.to(
{{target.name}},
{{reference.name}},
['{{reference.columns.lookup1}}', '{{reference.columns.lookup2}}'],
'{{target.columns.key}}',
) print(result)">result = add.to( patients, doctors, ['name', 'specialty'], 'doctor_id', ) print(result)
Using keyword arguments¶
result = add.to(
bring_to=patients,
bring_from=doctors,
bring='name',
against='doctor_id',
position='start',
) Lineage tracking¶
result = add.to(df, ref, 'name', 'id', lineage=True)
# View the lineage
lineage_report = add.scan('@lineage', result)
Lineage and as_type
lineage=True and as_type cannot be used together. Lineage metadata is stored in the DataFrame's native format and would be lost during type conversion.
Next Steps¶
- Pipe Compatibility — fluent chaining patterns
- Lineage Tracking — trace where columns came from
- Type Handling — pandas/polars interop