snowflake.snowpark.DataFrameAIFunctions.complete

DataFrameAIFunctions.complete(prompt: str, input_columns: Union[List[Column], Dict[str, Column]], model: str, *, output_column: Optional[str] = None, model_parameters: Optional[Dict[str, Any]] = None, return_error_details: Optional[bool] = None) → snowflake.snowpark.DataFrame[source]

Generate a response (completion) on each row using the specified language model.

Parameters:

  • prompt – The prompt template string. Use placeholders like {name} when passing a dict of columns, or {0}, {1} when passing a list.

  • input_columns – A list of Columns (positional placeholders {0}, {1}, …) or a dict mapping placeholder names to Columns.

  • model – A string specifying the model to be used. Different input types have different supported models. See details in AI_COMPLETE.

  • output_column – The name of the output column to be appended. If not provided, a column named AI_COMPLETE_OUTPUT is appended

  • model_parameters –

    Optional dict containing model hyperparameters:

    • temperature: Value from 0 to 1 controlling randomness (default: 0)

    • top_p: Value from 0 to 1 controlling diversity (default: 0)

    • max_tokens: Maximum number of output tokens (default: 4096, max: 8192)

    • guardrails: Enable Cortex Guard filtering (default: False)

  • return_error_details – When True, returns an OBJECT with value and error fields instead of returning NULL on failure.

Note

response_format and show_details from ai_complete() are not exposed here because this method always builds a PROMPT object from prompt / input_columns, and those options are only supported for the single-string AI_COMPLETE overload. Use ai_complete() directly for structured outputs or detailed responses.

Returns:

A new DataFrame with appended output columns at the end.

Examples:

>>> # Single column output with named placeholder
>>> from snowflake.snowpark.functions import col
>>> df = session.create_dataframe(
...     [["What is machine learning?"], ["Explain quantum computing"]],
...     schema=["question"]
... )
>>> result_df = df.ai.complete(
...     prompt="Answer this question briefly: {q}",
...     input_columns={"q": col("question")},
...     output_column="answer",
...     model="llama3.1-8b"
... )
>>> result_df.columns
['QUESTION', 'ANSWER']
>>> result_df.count()
2

>>> #  Processing images with file input
>>> from snowflake.snowpark.functions import to_file
>>> # Upload images to a stage first
>>> _ = session.sql("CREATE OR REPLACE TEMP STAGE mystage ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')").collect()
>>> _ = session.file.put("tests/resources/kitchen.png", "@mystage", auto_compress=False)
>>> _ = session.file.put("tests/resources/dog.jpg", "@mystage", auto_compress=False)
>>> # Create DataFrame with image paths and questions
>>> df = session.create_dataframe(
...     [
...         ["@mystage/kitchen.png", "What appliances are visible in this image?"],
...         ["@mystage/dog.jpg", "What animal is in this image?"]
...     ],
...     schema=["image_path", "question"]
... )
>>> # Use ai.complete with image files
>>> result_df = df.ai.complete(
...     prompt="Image: {0}, Question: {1}",
...     input_columns=[
...         to_file(col("image_path")),
...         col("question")
...     ],
...     output_column="answer",
...     model="claude-4-sonnet"
... )
>>> result_df.columns
['IMAGE_PATH', 'QUESTION', 'ANSWER']
>>> result_df.count()
2
>>> results = result_df.collect()
>>> 'microwave' in results[0]["ANSWER"].lower()
True
>>> 'dog' in results[1]["ANSWER"].lower()
True