.. _advanced_filters:

Advanced filters
================

``dataset`` provides two methods for running queries: :py:meth:`table.find() <dataset.Table.find>`
and :py:meth:`db.query() <dataset.Database.query>`. The table find helper method provides 
limited, but simple filtering options::

    results = table.find(column={operator: value})
    # e.g.:
    results = table.find(name={'like': '%mole rat%'})

A special form is using keyword searches on specific columns::

    results = table.find(value=5)
    # equal to:
    results = table.find(value={'=': 5})

    # Lists, tuples and sets are turned into `IN` queries:
    results = table.find(category=('foo', 'bar'))
    # equal to:
    results = table.find(value={'in': ('foo', 'bar')})

The following comparison operators are supported:

============== ============================================================
Operator       Description
============== ============================================================
gt, >          Greater than
lt, <          Less than
gte, >=        Greater or equal
lte, <=        Less or equal
!=, <>, not    Not equal to a single value
in             Value is in the given sequence
like, ilike    Text search, ILIKE is case-insensitive. Use ``%`` as a wildcard
between, ..    Value is between two values in the given tuple
startswith     String starts with
endswith       String ends with
============== ============================================================

Querying for a specific value on a column that does not exist on the table
will return no results.

You can also pass additional SQLAlchemy clauses into the :py:meth:`table.find() <dataset.Table.find>` method
by falling back onto the SQLAlchemy core objects wrapped by `dataset`::

    # Get the column `city` from the dataset table:
    column = table.table.columns.city
    # Define a SQLAlchemy clause:
    clause = column.ilike('amsterda%')
    # Query using the clause:
    results = table.find(clause)

This can also be used to define combined OR clauses if needed (e.g. `city = 'Bla' OR country = 'Foo'`).

Queries using raw SQL
---------------------

To run more complex queries with JOINs, or to perform GROUP BY-style
aggregation, you can also use :py:meth:`db.query() <dataset.Database.query>`
to run raw SQL queries instead. This also supports paramterisation to avoid
SQL injections.

Finally, you should consider falling back to SQLAlchemy_ core to construct
queries if you are looking for a programmatic, composable method of generating
SQL in Python.

.. _SQLALchemy: https://docs.sqlalchemy.org/