add_column
Add a new column to a dataframe with constant values, lists, or computed formulas to enhance data structure and analysis capabilities.
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 main handler function implementing the 'add_column' tool. It adds a new column to the DataFrame in the current session using either a constant value, a list of values matching row count, or a secure formula expression. Handles validation for existing columns and list lengths, uses secure evaluation for formulas.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:647-658 (registration)Registration block where the add_column function is registered as a tool on the FastMCP column_server instance, along with other column operation tools.column_server = FastMCP( "DataBeak Column Operations Server", instructions="Column-level operations server providing selection, renaming, addition, removal, and type conversion", ) # Register the functions as MCP tools column_server.tool(name="select_columns")(select_columns) column_server.tool(name="rename_columns")(rename_columns) column_server.tool(name="add_column")(add_column) column_server.tool(name="remove_columns")(remove_columns) column_server.tool(name="change_column_type")(change_column_type) column_server.tool(name="update_column")(update_column)
- Input schema defined via Annotated types and Pydantic Field descriptions in the function signature. Returns ColumnOperationResult.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], )