def has_substructure(
    mol: ColumnElement[AnyBingoMol], query: TextLike, parameters: TextLike = ""
):
    """
    Perform substructure search on a molecule column.

    Parameters
    ----------
    mol : ColumnElement
        SQLAlchemy column containing molecule data (SMILES, Molfile, or binary).
    query : TextLike
        Query molecule as SMILES, SMARTS, or Molfile string.
    parameters : TextLike, optional
        Search parameters for customizing the matching behavior (default is "").
        Examples: "TAU" for tautomer search, "RES" for resonance search.

    Returns
    -------
    BinaryExpression
        SQLAlchemy expression for substructure matching that can be used in WHERE clauses.
    
    """
    return mol.op("@")(text(f"('{query}', '{parameters}')::bingo.sub"))


def matches_smarts(
    mol: ColumnElement[AnyBingoMol], query: TextLike, parameters: TextLike = ""
):
    """
    Perform SMARTS pattern matching on a molecule column.

    Parameters
    ----------
    mol : ColumnElement[AnyBingoMol]
        SQLAlchemy column containing molecule data (SMILES, Molfile, or binary).
    query : TextLike
        SMARTS pattern string for matching.
    parameters : TextLike, optional
        Search parameters for customizing the matching behavior (default is "").

    Returns
    -------
    BinaryExpression
        SQLAlchemy expression for SMARTS matching that can be used in WHERE clauses.

    """
    return mol.op("@")(text(f"('{query}', '{parameters}')::bingo.smarts"))


def mol_equals(mol: ColumnElement[AnyBingoMol], query: TextLike, parameters: TextLike = ""):
    """
    Perform exact structure matching on a molecule column.

    Parameters
    ----------
    mol : ColumnElement[AnyBingoMol]
        SQLAlchemy column containing molecule data (SMILES, Molfile, or binary).
    query : TextLike
        Query molecule as SMILES or Molfile string for exact matching.
    parameters : TextLike, optional
        Search parameters for customizing the matching behavior (default is "").
        Examples: "TAU" for tautomer matching, "STE" for stereochemistry.

    Returns
    -------
    BinaryExpression
        SQLAlchemy expression for exact matching that can be used in WHERE clauses.

    """
    return mol.op("@")(text(f"('{query}', '{parameters}')::bingo.exact"))


def similarity(
    mol: ColumnElement[AnyBingoMol],
    query: TextLike,
    bottom: float = 0.0,
    top: float = 1.0,
    metric: TextLike = "Tanimoto",
) -> BinaryExpression:
    """
    Perform similarity search on a molecule column. This should be used in WHERE clauses, as it
    returns a boolean expression indicating whether the similarity criteria are met.

    Parameters
    ----------
    mol : AnyBingoMolLike | AnyBingoBinaryMolLike
        SQLAlchemy column containing molecule data (SMILES, Molfile, or binary).
    query : TextLike
        Query molecule as SMILES or Molfile string for similarity comparison.
    bottom : float, optional
        Minimum similarity threshold (default is 0.0).
    top : float, optional
        Maximum similarity threshold (default is 1.0).
    metric : TextLike, optional
        Similarity metric to use (default is "Tanimoto").
        Other options include "Dice", "Cosine", etc.

    Returns
    -------
    BinaryExpression
        SQLAlchemy expression for similarity matching that can be used in WHERE clauses.

    """
    return mol.op("%")(
        text(f"('{query}', {bottom}, {top}, '{metric}')::bingo.sim")
    )