add_column
Add new columns to dataframes with constant values, lists, or computed formulas for data transformation and analysis.
Instructions
Add a new column to the dataframe.
Returns: ColumnOperationResult with operation details
Examples: # Add column with constant value add_column(ctx, "status", "active")
# Add column with list of values
add_column(ctx, "scores", [85, 90, 78, 92, 88])
# Add computed column
add_column(ctx, "total", formula="price * quantity")
# Add column with complex formula
add_column(ctx, "full_name", formula="first_name + ' ' + last_name")
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name for the new column to add | |
| value | No | Single value for all rows or list of values (one per row) | |
| formula | No | Safe mathematical expression to compute column values (e.g., 'col1 + col2') |
Implementation Reference
- The async handler function implementing the add_column tool logic: adds a new column to the DataFrame using either a constant value, a list matching row count, or a secure formula evaluation.async def add_column( ctx: Annotated[Context, Field(description="FastMCP context for session access")], name: Annotated[str, Field(description="Name for the new column to add")], value: Annotated[ CellValue | list[CellValue], Field(description="Single value for all rows or list of values (one per row)"), ] = None, formula: Annotated[ SecureExpression | str | None, Field( description="Safe mathematical expression to compute column values (e.g., 'col1 + col2')", ), ] = None, ) -> ColumnOperationResult: """Add a new column to the dataframe. Returns: ColumnOperationResult with operation details Examples: # Add column with constant value add_column(ctx, "status", "active") # Add column with list of values add_column(ctx, "scores", [85, 90, 78, 92, 88]) # Add computed column add_column(ctx, "total", formula="price * quantity") # Add column with complex formula add_column(ctx, "full_name", formula="first_name + ' ' + last_name") """ # Get session_id from FastMCP context session_id = ctx.session_id _session, df = get_session_data(session_id) if name in df.columns: msg = "name" raise InvalidParameterError(msg, name, f"Column '{name}' already exists") if formula: try: # Convert string to SecureExpression if needed if isinstance(formula, str): formula = SecureExpression(expression=formula) # Use secure evaluator instead of pandas.eval evaluator = get_secure_expression_evaluator() result = evaluator.evaluate_simple_formula(formula.expression, df) df[name] = result except Exception as e: msg = "formula" raise InvalidParameterError(msg, formula, f"Invalid formula: {e}") from e elif isinstance(value, list): if len(value) != len(df): msg = "value" raise InvalidParameterError( msg, str(value), f"List length ({len(value)}) must match row count ({len(df)})", ) df[name] = value else: # Single value for all rows df[name] = value # No longer recording operations (simplified MCP architecture) return ColumnOperationResult( operation="add", rows_affected=len(df), columns_affected=[name], )
- src/databeak/servers/column_server.py:655-655 (registration)Registration of the add_column handler as a tool on the FastMCP column_server instance.column_server.tool(name="add_column")(add_column)
- Input schema defined via Annotated type hints with Pydantic Field descriptions in the function signature.ctx: Annotated[Context, Field(description="FastMCP context for session access")], name: Annotated[str, Field(description="Name for the new column to add")], value: Annotated[ CellValue | list[CellValue], Field(description="Single value for all rows or list of values (one per row)"), ] = None, formula: Annotated[ SecureExpression | str | None, Field( description="Safe mathematical expression to compute column values (e.g., 'col1 + col2')", ), ] = None, ) -> ColumnOperationResult: """Add a new column to the dataframe. Returns: ColumnOperationResult with operation details Examples: # Add column with constant value add_column(ctx, "status", "active") # Add column with list of values add_column(ctx, "scores", [85, 90, 78, 92, 88]) # Add computed column add_column(ctx, "total", formula="price * quantity") # Add column with complex formula add_column(ctx, "full_name", formula="first_name + ' ' + last_name") """ # Get session_id from FastMCP context session_id = ctx.session_id _session, df = get_session_data(session_id) if name in df.columns: msg = "name" raise InvalidParameterError(msg, name, f"Column '{name}' already exists") if formula: try: # Convert string to SecureExpression if needed if isinstance(formula, str): formula = SecureExpression(expression=formula) # Use secure evaluator instead of pandas.eval evaluator = get_secure_expression_evaluator() result = evaluator.evaluate_simple_formula(formula.expression, df) df[name] = result except Exception as e: msg = "formula" raise InvalidParameterError(msg, formula, f"Invalid formula: {e}") from e elif isinstance(value, list): if len(value) != len(df): msg = "value" raise InvalidParameterError( msg, str(value), f"List length ({len(value)}) must match row count ({len(df)})", ) df[name] = value else: # Single value for all rows df[name] = value # No longer recording operations (simplified MCP architecture) return ColumnOperationResult( operation="add", rows_affected=len(df), columns_affected=[name], )