Filtering

The filterBy method of the database endpoint is the general shorthand to filter results and can accept different types of filters. Filters can be combined to create complex filtering conditions.

Using a filter

use FiveamCode\LaravelNotionApi\Query\Filters\Filter;
use FiveamCode\LaravelNotionApi\Query\Filters\Operators;

// Filter condition: ('Birth year' EQUALS 1922)
$birthYear = Filter::numberFilter("Birth year", Operators::EQUALS, 1922);

Notion::database("8284f3ff77e24d4a939d19459e4d6bdc")
        ->filterBy($birthYear)
        ->query()
        ->asCollection();

// Returns Kathleen Booth and Marlyn Meltzer from our Test Database: https://www.notion.so/8284f3ff77e24d4a939d19459e4d6bdc

Filter Types

We aim to implement each available filter object of the API with a convenient instance method. As long as the other filter types aren't implemented as dedicated methods, you can use the rawFilter like in the example below.

The following filter types are implemented so far:

Text properties

$filter = Filter::textFilter('Name', Operators::EQUALS, 'Ada Lovelace');

Valid operators: EQUALS, DOES_NOT_EQUAL, CONTAINS, DOES_NOT_CONTAIN, STARTS_WITH, ENDS_WITH, IS_EMPTY, IS_NOT_EMPTY.

Number properties

$filter = Filter::numberFilter("Birth year", Operators::GREATER_THAN_OR_EQUAL_TO, 1906);

Valid operators: EQUALS, DOES_NOT_EQUAL, GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUAL_TO, LESS_THAN_OR_EQUAL_TO, IS_EMPTY, IS_NOT_EMPTY.

Raw filters

// Filter condition: ('Known for' CONTAINS 'COBOL')
$filter = Filter::rawFilter(
            "Known for",
            [
                "multi_select" =>
                    [Operators::CONTAINS => "COBOL"]
            ]
        );

Compound filters

You can build more complex queries by combining filters within filter bags.

Filter bags

A FilterBag can work with the operators AND or OR and it can contain filters as well as other filter bags.

To quickly create a filter bag with the AND operator, you can use the FilterBag::and() method. The same goes for the OR operator.

$andFilter = FilterBag::and();
$orFilter = FilterBag::or();

You can add filters to a filter bag by using the addFilter method and filter bags by using the addFilterBag method. There's also a addFilters method available which accepts a Collection of filters.

Examples

Filter bag with two filters, connected by the OR operator:

use Illuminate\Support\Collection;
use FiveamCode\LaravelNotionApi\Query\Filters\Filter;
use FiveamCode\LaravelNotionApi\Query\Filters\Operators;
use FiveamCode\LaravelNotionApi\Query\Filters\FilterBag;

// Filter condition: ('Name' EQUALS 'Ada Lovelace' || 'Known for' CONTAINS 'COBOL')
$filterBag = new FilterBag(Operators::OR);

$filterBag->addFilter(
    Filter::textFilter("Name", Operators::EQUALS, "Ada Lovelace")
);

$filterBag->addFilter(
    Filter::rawFilter("Known for", [
        "multi_select" => [Operators::CONTAINS => "COBOL"],
    ])
);

Notion::database("8284f3ff77e24d4a939d19459e4d6bdc")
    ->filterBy($filterBag)
    ->query()
    ->asCollection();
// Returns Ada Lovelace and Grace Hopper from our Test Database: https://www.notion.so/8284f3ff77e24d4a939d19459e4d6bdc

Filter bag with one filter and one filter bag (OR operator), connected by the AND operator:

use Illuminate\Support\Collection;
use FiveamCode\LaravelNotionApi\Query\Filters\Filter;
use FiveamCode\LaravelNotionApi\Query\Filters\FilterBag;
use FiveamCode\LaravelNotionApi\Query\Filters\Operators;
use FiveamCode\LaravelNotionApi\Query\Sorting;

// Filter condition: ('Known for' CONTAINS 'Univac' && ('Name' EQUALS 'Grace' || 'Name' EQUALS 'Jean'))
$filterBag = new FilterBag(Operators::AND);

$filterBag->addFilter(
    Filter::rawFilter("Known for", [
        "multi_select" => [Operators::CONTAINS => "UNIVAC"],
    ])
);

$nameFilterBag = new FilterBag(Operators::OR);
$nameFilterBag
    ->addFilter(Filter::textFilter("Name", Operators::EQUALS, "Grace Hopper"))
    ->addFilter(Filter::textFilter("Name", Operators::EQUALS, "Jean Bartik"));

$filterBag->addFilterBag($nameFilterBag);

Notion::database("8284f3ff77e24d4a939d19459e4d6bdc")
    ->filterByBag($filterBag)
    ->query()
    ->asCollection();
// Returns Jean Bartik and Grace Hopper from our Test Database: https://www.notion.so/8284f3ff77e24d4a939d19459e4d6bdc

Collections

To keep backwards compatibility, it is still possible to pass a Collection instance with filters to the filterBy method of the database endpoint. This collection will be converted to a FilterBag with the OR operator internally.