Execute a BlendSQL Query

BlendSQL Class

Core BlendSQL class that provides high level interface for executing BlendSQL queries.

Parameters:

Name	Type	Description	Default
db	Union[DataFrame, dict, str, Database]	Database to connect to. Can be: pandas DataFrame or dict of DataFrames Path to SQLite database file PostgreSQL connection string Database object	None
model	Optional[Model]	Model instance to use for LLM operations. Can also be provided during query execution.	None
ingredients	Optional[Collection[Type[Ingredient]]]	Collection of ingredients to make available for queries. Can also be provided during query execution.	list()
verbose	bool	Whether to output debug logging information. Defaults to False.	False
infer_gen_constraints	bool	Whether to automatically infer constraints for LLM generation based on query context. Defaults to True.	True
table_to_title	Optional[Dict[str, str]]	Optional mapping from table names to descriptive titles, useful for datasets where table titles contain metadata.	None
schema_qualify	bool	Whether to qualify column names with table names. Required for multi-table queries but adds overhead. Can be disabled for single-table queries. Defaults to True.	True

Source code in blendsql/blendsql.py

@dataclass
class BlendSQL:
    """Core `BlendSQL` class that provides high level interface for executing BlendSQL queries.

    Args:
        db (Union[pd.DataFrame, dict, str, Database]): Database to connect to. Can be:

            - pandas DataFrame or dict of DataFrames

            - Path to SQLite database file

            - PostgreSQL connection string

            - `Database` object
        model (Optional[Model]): Model instance to use for LLM operations. Can also be
            provided during query execution.
        ingredients (Optional[Collection[Type[Ingredient]]]): Collection of ingredients to
            make available for queries. Can also be
                provided during query execution.
        verbose (bool): Whether to output debug logging information. Defaults to False.
        infer_gen_constraints (bool): Whether to automatically infer constraints for
            LLM generation based on query context. Defaults to True.
        table_to_title (Optional[Dict[str, str]]): Optional mapping from table names to
            descriptive titles, useful for datasets where table titles contain metadata.
        schema_qualify (bool): Whether to qualify column names with table names. Required
            for multi-table queries but adds overhead. Can be disabled for single-table
            queries. Defaults to True.
    """

    db: t.Union[pd.DataFrame, dict, str, Database] = field(default=None)
    model: t.Optional[Model] = field(default=None)
    ingredients: t.Optional[Collection[t.Type[Ingredient]]] = field(
        default_factory=list
    )

    verbose: bool = field(default=False)
    infer_gen_constraints: bool = field(default=True)
    table_to_title: t.Optional[t.Dict[str, str]] = field(default=None)
    schema_qualify: bool = field(default=True)

    def __post_init__(self):
        if not isinstance(self.db, Database):
            self.db = self._infer_db_type(self.db)
        if self.db is None:
            raise ValueError("df_or_db_path must be provided")
        self.ingredients = self._merge_default_ingredients(self.ingredients)
        self._toggle_verbosity(self.verbose)

    @staticmethod
    def _toggle_verbosity(verbose_in_use: bool):
        def set_level(l: int):
            logger.setLevel(l)
            for handler in logger.handlers:
                handler.setLevel(l)

        if verbose_in_use:
            set_level(logging.DEBUG)
        else:
            set_level(logging.ERROR)

    @staticmethod
    def _merge_default_ingredients(
        ingredients: t.Optional[Collection[t.Type[Ingredient]]],
    ):
        from blendsql.ingredients import LLMQA, LLMMap, LLMJoin

        DEFAULT_INGREDIENTS = {LLMQA, LLMMap, LLMJoin}
        ingredients = set(ingredients)
        try:
            ingredient_names = {i.__name__ for i in ingredients}
        except AttributeError as e:
            raise IngredientException(
                "All arguments passed to `ingredients` should be `Ingredient` classes!"
            ) from e
        for default_ingredient in DEFAULT_INGREDIENTS:
            if default_ingredient.__name__ not in ingredient_names:
                ingredients.add(default_ingredient)
        return ingredients

    @staticmethod
    def _infer_db_type(df_or_db_path) -> Database:
        from pathlib import Path

        if df_or_db_path is None:
            from .db.pandas import Pandas

            return Pandas({})  # Load an empty DuckDB connection

        elif isinstance(df_or_db_path, (pd.DataFrame, dict)):
            from .db.pandas import Pandas

            return Pandas(df_or_db_path)
        elif isinstance(df_or_db_path, (str, Path)):
            if Path(df_or_db_path).exists():
                from .db.sqlite import SQLite

                return SQLite(df_or_db_path)
            else:
                from .db.postgresql import PostgreSQL

                return PostgreSQL(df_or_db_path)
        else:
            raise ValueError(
                f"Could not resolve '{df_or_db_path}' to a valid database type!"
            )

    def execute(
        self,
        query: str,
        ingredients: t.Optional[Collection[t.Type[Ingredient]]] = None,
        model: t.Optional[str] = None,
        infer_gen_constraints: t.Optional[bool] = None,
        schema_qualify: t.Optional[bool] = None,
        verbose: t.Optional[bool] = None,
    ) -> Smoothie:
        '''The `execute()` function is used to execute a BlendSQL query against a database and
        return the final result, in addition to the intermediate reasoning steps taken.
        Execution is done on a database given an ingredient context.

        Args:
            query: The BlendSQL query to execute
            ingredients: Collection of ingredient objects, to use in interpreting BlendSQL query
            verbose: Boolean defining whether to run with logger in debug mode
            default_model: Which BlendSQL model to use in performing ingredient tasks in the current query
            infer_gen_constraints: Optionally infer the output format of an `IngredientMap` call, given the predicate context
                For example, in `{{LLMMap('convert to date', 'w::listing date')}} <= '1960-12-31'`
                We can infer the output format should look like '1960-12-31' and both:
                    1) Put this string in the `example_outputs` kwarg
                    2) If we have a LocalModel, pass the '\d{4}-\d{2}-\d{2}' pattern to guidance
            table_to_title: Optional mapping from table name to title of table.
                Useful for datasets like WikiTableQuestions, where relevant info is stored in table title.
            schema_qualify: Optional bool, determines if we run qualify_columns() from sqlglot
                This enables us to write BlendSQL scripts over multi-table databases without manually qualifying columns ourselves
                However, we need to call `db.sqlglot_schema` if schema_qualify=True, which may add some latency.
                With single-table queries, we can set this to False.

        Returns:
            smoothie: `Smoothie` dataclass containing pd.DataFrame output and execution metadata

        Examples:
            ```python
            import pandas as pd

            from blendsql import BlendSQL, config
            from blendsql.ingredients import LLMMap, LLMQA, LLMJoin
            from blendsql.models import LiteLLM, TransformersLLM

            # Optionally set how many async calls to allow concurrently
            # This depends on your OpenAI/Anthropic/etc. rate limits
            config.set_async_limit(10)

            # Load model
            model = LiteLLM("openai/gpt-4o-mini") # requires .env file with `OPENAI_API_KEY`
            # model = LiteLLM("anthropic/claude-3-haiku-20240307") # requires .env file with `ANTHROPIC_API_KEY`
            # model = TransformersLLM(
            #    "meta-llama/Llama-3.2-1B-Instruct",
            #    config={"chat_template": Llama3ChatTemplate, "device_map": "auto"},
            # ) # run with any local Transformers model

            # Prepare our BlendSQL connection
            bsql = BlendSQL(
                {
                    "People": pd.DataFrame(
                        {
                            "Name": [
                                "George Washington",
                                "John Quincy Adams",
                                "Thomas Jefferson",
                                "James Madison",
                                "James Monroe",
                                "Alexander Hamilton",
                                "Sabrina Carpenter",
                                "Charli XCX",
                                "Elon Musk",
                                "Michelle Obama",
                                "Elvis Presley",
                            ],
                            "Known_For": [
                                "Established federal government, First U.S. President",
                                "XYZ Affair, Alien and Sedition Acts",
                                "Louisiana Purchase, Declaration of Independence",
                                "War of 1812, Constitution",
                                "Monroe Doctrine, Missouri Compromise",
                                "Created national bank, Federalist Papers",
                                "Nonsense, Emails I Cant Send, Mean Girls musical",
                                "Crash, How Im Feeling Now, Boom Clap",
                                "Tesla, SpaceX, Twitter/X acquisition",
                                "Lets Move campaign, Becoming memoir",
                                "14 Grammys, King of Rock n Roll",
                            ],
                        }
                    ),
                    "Eras": pd.DataFrame({"Years": ["1800-1900", "1900-2000", "2000-Now"]}),
                },
                ingredients={LLMMap, LLMQA, LLMJoin},
                model=model,
            )

            smoothie = bsql.execute(
                """
                SELECT * FROM People P
                WHERE P.Name IN {{
                    LLMQA('First 3 presidents of the U.S?', quantifier='{3}')
                }}
                """
            )

            print(smoothie.df)
            # ┌───────────────────┬───────────────────────────────────────────────────────┐
            # │ Name              │ Known_For                                             │
            # ├───────────────────┼───────────────────────────────────────────────────────┤
            # │ George Washington │ Established federal government, First U.S. Preside... │
            # │ John Quincy Adams │ XYZ Affair, Alien and Sedition Acts                   │
            # │ Thomas Jefferson  │ Louisiana Purchase, Declaration of Independence       │
            # └───────────────────┴───────────────────────────────────────────────────────┘
            print(smoothie.summary())
            # ┌────────────┬──────────────────────┬─────────────────┬─────────────────────┐
            # │   Time (s) │   # Generation Calls │   Prompt Tokens │   Completion Tokens │
            # ├────────────┼──────────────────────┼─────────────────┼─────────────────────┤
            # │    1.25158 │                    1 │             296 │                  16 │
            # └────────────┴──────────────────────┴─────────────────┴─────────────────────┘
            ```
        '''

        self._toggle_verbosity(verbose if verbose is not None else self.verbose)

        start = time.time()
        model_in_use = model or self.model
        try:
            smoothie = _blend(
                query=query,
                db=self.db,
                default_model=model_in_use,
                ingredients=self._merge_default_ingredients(
                    ingredients or self.ingredients
                ),
                infer_gen_constraints=infer_gen_constraints
                if infer_gen_constraints is not None
                else self.infer_gen_constraints,
                table_to_title=self.table_to_title,
                schema_qualify=schema_qualify
                if schema_qualify is not None
                else self.schema_qualify,
            )
        except Exception as error:
            raise error
        finally:
            # In the case of a recursive `_blend()` call,
            #   this logic allows temp tables to persist until
            #   the final base case is fulfilled.
            self.db._reset_connection()
        smoothie.meta.process_time_seconds = time.time() - start
        # Reset model stats, so future executions don't add here
        if model_in_use is not None:
            model_in_use.reset_stats()
        return smoothie

execute(query, ingredients=None, model=None, infer_gen_constraints=None, schema_qualify=None, verbose=None)

The execute() function is used to execute a BlendSQL query against a database and return the final result, in addition to the intermediate reasoning steps taken. Execution is done on a database given an ingredient context.

Parameters:

Name	Type	Description	Default
query	str	The BlendSQL query to execute	required
ingredients	Optional[Collection[Type[Ingredient]]]	Collection of ingredient objects, to use in interpreting BlendSQL query	None
verbose	Optional[bool]	Boolean defining whether to run with logger in debug mode	None
default_model		Which BlendSQL model to use in performing ingredient tasks in the current query	required
infer_gen_constraints	Optional[bool]	Optionally infer the output format of an IngredientMap call, given the predicate context For example, in {{LLMMap('convert to date', 'w::listing date')}} <= '1960-12-31' We can infer the output format should look like '1960-12-31' and both: 1) Put this string in the example_outputs kwarg 2) If we have a LocalModel, pass the '\d{4}-\d{2}-\d{2}' pattern to guidance	None
table_to_title		Optional mapping from table name to title of table. Useful for datasets like WikiTableQuestions, where relevant info is stored in table title.	required
schema_qualify	Optional[bool]	Optional bool, determines if we run qualify_columns() from sqlglot This enables us to write BlendSQL scripts over multi-table databases without manually qualifying columns ourselves However, we need to call db.sqlglot_schema if schema_qualify=True, which may add some latency. With single-table queries, we can set this to False.	None

Returns:

Name	Type	Description
smoothie	Smoothie	Smoothie dataclass containing pd.DataFrame output and execution metadata

Examples:

import pandas as pd

from blendsql import BlendSQL, config
from blendsql.ingredients import LLMMap, LLMQA, LLMJoin
from blendsql.models import LiteLLM, TransformersLLM

# Optionally set how many async calls to allow concurrently
# This depends on your OpenAI/Anthropic/etc. rate limits
config.set_async_limit(10)

# Load model
model = LiteLLM("openai/gpt-4o-mini") # requires .env file with `OPENAI_API_KEY`
# model = LiteLLM("anthropic/claude-3-haiku-20240307") # requires .env file with `ANTHROPIC_API_KEY`
# model = TransformersLLM(
#    "meta-llama/Llama-3.2-1B-Instruct",
#    config={"chat_template": Llama3ChatTemplate, "device_map": "auto"},
# ) # run with any local Transformers model

# Prepare our BlendSQL connection
bsql = BlendSQL(
    {
        "People": pd.DataFrame(
            {
                "Name": [
                    "George Washington",
                    "John Quincy Adams",
                    "Thomas Jefferson",
                    "James Madison",
                    "James Monroe",
                    "Alexander Hamilton",
                    "Sabrina Carpenter",
                    "Charli XCX",
                    "Elon Musk",
                    "Michelle Obama",
                    "Elvis Presley",
                ],
                "Known_For": [
                    "Established federal government, First U.S. President",
                    "XYZ Affair, Alien and Sedition Acts",
                    "Louisiana Purchase, Declaration of Independence",
                    "War of 1812, Constitution",
                    "Monroe Doctrine, Missouri Compromise",
                    "Created national bank, Federalist Papers",
                    "Nonsense, Emails I Cant Send, Mean Girls musical",
                    "Crash, How Im Feeling Now, Boom Clap",
                    "Tesla, SpaceX, Twitter/X acquisition",
                    "Lets Move campaign, Becoming memoir",
                    "14 Grammys, King of Rock n Roll",
                ],
            }
        ),
        "Eras": pd.DataFrame({"Years": ["1800-1900", "1900-2000", "2000-Now"]}),
    },
    ingredients={LLMMap, LLMQA, LLMJoin},
    model=model,
)

smoothie = bsql.execute(
    """
    SELECT * FROM People P
    WHERE P.Name IN {{
        LLMQA('First 3 presidents of the U.S?', quantifier='{3}')
    }}
    """
)

print(smoothie.df)
# ┌───────────────────┬───────────────────────────────────────────────────────┐
# │ Name              │ Known_For                                             │
# ├───────────────────┼───────────────────────────────────────────────────────┤
# │ George Washington │ Established federal government, First U.S. Preside... │
# │ John Quincy Adams │ XYZ Affair, Alien and Sedition Acts                   │
# │ Thomas Jefferson  │ Louisiana Purchase, Declaration of Independence       │
# └───────────────────┴───────────────────────────────────────────────────────┘
print(smoothie.summary())
# ┌────────────┬──────────────────────┬─────────────────┬─────────────────────┐
# │   Time (s) │   # Generation Calls │   Prompt Tokens │   Completion Tokens │
# ├────────────┼──────────────────────┼─────────────────┼─────────────────────┤
# │    1.25158 │                    1 │             296 │                  16 │
# └────────────┴──────────────────────┴─────────────────┴─────────────────────┘

Source code in blendsql/blendsql.py

def execute(
    self,
    query: str,
    ingredients: t.Optional[Collection[t.Type[Ingredient]]] = None,
    model: t.Optional[str] = None,
    infer_gen_constraints: t.Optional[bool] = None,
    schema_qualify: t.Optional[bool] = None,
    verbose: t.Optional[bool] = None,
) -> Smoothie:
    '''The `execute()` function is used to execute a BlendSQL query against a database and
    return the final result, in addition to the intermediate reasoning steps taken.
    Execution is done on a database given an ingredient context.

    Args:
        query: The BlendSQL query to execute
        ingredients: Collection of ingredient objects, to use in interpreting BlendSQL query
        verbose: Boolean defining whether to run with logger in debug mode
        default_model: Which BlendSQL model to use in performing ingredient tasks in the current query
        infer_gen_constraints: Optionally infer the output format of an `IngredientMap` call, given the predicate context
            For example, in `{{LLMMap('convert to date', 'w::listing date')}} <= '1960-12-31'`
            We can infer the output format should look like '1960-12-31' and both:
                1) Put this string in the `example_outputs` kwarg
                2) If we have a LocalModel, pass the '\d{4}-\d{2}-\d{2}' pattern to guidance
        table_to_title: Optional mapping from table name to title of table.
            Useful for datasets like WikiTableQuestions, where relevant info is stored in table title.
        schema_qualify: Optional bool, determines if we run qualify_columns() from sqlglot
            This enables us to write BlendSQL scripts over multi-table databases without manually qualifying columns ourselves
            However, we need to call `db.sqlglot_schema` if schema_qualify=True, which may add some latency.
            With single-table queries, we can set this to False.

    Returns:
        smoothie: `Smoothie` dataclass containing pd.DataFrame output and execution metadata

    Examples:
        ```python
        import pandas as pd

        from blendsql import BlendSQL, config
        from blendsql.ingredients import LLMMap, LLMQA, LLMJoin
        from blendsql.models import LiteLLM, TransformersLLM

        # Optionally set how many async calls to allow concurrently
        # This depends on your OpenAI/Anthropic/etc. rate limits
        config.set_async_limit(10)

        # Load model
        model = LiteLLM("openai/gpt-4o-mini") # requires .env file with `OPENAI_API_KEY`
        # model = LiteLLM("anthropic/claude-3-haiku-20240307") # requires .env file with `ANTHROPIC_API_KEY`
        # model = TransformersLLM(
        #    "meta-llama/Llama-3.2-1B-Instruct",
        #    config={"chat_template": Llama3ChatTemplate, "device_map": "auto"},
        # ) # run with any local Transformers model

        # Prepare our BlendSQL connection
        bsql = BlendSQL(
            {
                "People": pd.DataFrame(
                    {
                        "Name": [
                            "George Washington",
                            "John Quincy Adams",
                            "Thomas Jefferson",
                            "James Madison",
                            "James Monroe",
                            "Alexander Hamilton",
                            "Sabrina Carpenter",
                            "Charli XCX",
                            "Elon Musk",
                            "Michelle Obama",
                            "Elvis Presley",
                        ],
                        "Known_For": [
                            "Established federal government, First U.S. President",
                            "XYZ Affair, Alien and Sedition Acts",
                            "Louisiana Purchase, Declaration of Independence",
                            "War of 1812, Constitution",
                            "Monroe Doctrine, Missouri Compromise",
                            "Created national bank, Federalist Papers",
                            "Nonsense, Emails I Cant Send, Mean Girls musical",
                            "Crash, How Im Feeling Now, Boom Clap",
                            "Tesla, SpaceX, Twitter/X acquisition",
                            "Lets Move campaign, Becoming memoir",
                            "14 Grammys, King of Rock n Roll",
                        ],
                    }
                ),
                "Eras": pd.DataFrame({"Years": ["1800-1900", "1900-2000", "2000-Now"]}),
            },
            ingredients={LLMMap, LLMQA, LLMJoin},
            model=model,
        )

        smoothie = bsql.execute(
            """
            SELECT * FROM People P
            WHERE P.Name IN {{
                LLMQA('First 3 presidents of the U.S?', quantifier='{3}')
            }}
            """
        )

        print(smoothie.df)
        # ┌───────────────────┬───────────────────────────────────────────────────────┐
        # │ Name              │ Known_For                                             │
        # ├───────────────────┼───────────────────────────────────────────────────────┤
        # │ George Washington │ Established federal government, First U.S. Preside... │
        # │ John Quincy Adams │ XYZ Affair, Alien and Sedition Acts                   │
        # │ Thomas Jefferson  │ Louisiana Purchase, Declaration of Independence       │
        # └───────────────────┴───────────────────────────────────────────────────────┘
        print(smoothie.summary())
        # ┌────────────┬──────────────────────┬─────────────────┬─────────────────────┐
        # │   Time (s) │   # Generation Calls │   Prompt Tokens │   Completion Tokens │
        # ├────────────┼──────────────────────┼─────────────────┼─────────────────────┤
        # │    1.25158 │                    1 │             296 │                  16 │
        # └────────────┴──────────────────────┴─────────────────┴─────────────────────┘
        ```
    '''

    self._toggle_verbosity(verbose if verbose is not None else self.verbose)

    start = time.time()
    model_in_use = model or self.model
    try:
        smoothie = _blend(
            query=query,
            db=self.db,
            default_model=model_in_use,
            ingredients=self._merge_default_ingredients(
                ingredients or self.ingredients
            ),
            infer_gen_constraints=infer_gen_constraints
            if infer_gen_constraints is not None
            else self.infer_gen_constraints,
            table_to_title=self.table_to_title,
            schema_qualify=schema_qualify
            if schema_qualify is not None
            else self.schema_qualify,
        )
    except Exception as error:
        raise error
    finally:
        # In the case of a recursive `_blend()` call,
        #   this logic allows temp tables to persist until
        #   the final base case is fulfilled.
        self.db._reset_connection()
    smoothie.meta.process_time_seconds = time.time() - start
    # Reset model stats, so future executions don't add here
    if model_in_use is not None:
        model_in_use.reset_stats()
    return smoothie