Своя таблица

Если данные лежат в своей таблице базы сайта (остатки по складам, рейтинги, связи), их можно взять в фильтр без кода. Проще всего — вкладка «Источники» → «Своя таблица»: выберите таблицу и колонки, нажмите «Проверить», затем «Добавить в набор». То же в JSON набора:

"sql": {
    "stock_msk": {
        "table": "shop_stock",
        "link": "product_id",
        "value": "qty",
        "kind": "number",
        "agg": "sum",
        "where": {"warehouse": "msk"},
        "label": "Остаток в Москве"
    },
    "badge": {
        "table": "shop_badges", "link": "resource_id", "value": "badge_id",
        "labels": {"table": "shop_badge_names", "id": "id", "name": "name"},
        "label": "Значки"
    }
},
"numbers": {"sql:stock_msk": {}},
"facets":  {"sql:badge": {}}
tableтаблица без префикса таблиц сайта (с полным именем — добавьте "prefix": false)
linkколонка с id товара (ресурса)
valueколонка значения
kindtext, number, date (timestamp или дата строкой), bool
aggесли у товара несколько строк: list — все значения (по умолчанию для text), sum, min, max, first (по умолчанию для чисел и дат)
whereусловия «колонка = значение»
orderколонка порядка строк товара (для first)
labelsсправочник подписей: в фильтре вместо id будет название

Свой PHP-источник

Для вычисляемых данных (скидка в процентах, данные внешнего API, сложные связи) напишите класс-источник. Он отдаёт список полей и значения для пачки товаров одним запросом:

 ['label' => 'Скидка, %', 'kind' => 'number']];
    }

    /** Значения для пачки товаров: [id => [поле => значение]] */
    public function load(array $ids, array $fields): array
    {
        $out = [];
        $sql = 'SELECT id, price, old_price FROM ' . $this->table('ms3_products')
            . ' WHERE id IN (' . self::in($ids) . ') AND old_price > price';
        foreach ($this->rows($sql) as $r) {
            $out[(int)$r['id']]['discount'] = round(($r['old_price'] - $r['price']) / $r['old_price'] * 100);
        }
        return $out;
    }
}

Подключение в наборе (вкладка JSON):

"providers": [{"class": "MyShop\\BitFacet\\DiscountProvider", "options": {}}],
"numbers": {"calc:discount": {"label": "Скидка, %"}}

Сообщить об изменениях из своего кода

Импорт или скрипт меняет товары напрямую в базе — сообщите BitFacet, и изменения попадут в фильтр без полной пересборки:

$bf = $modx->services->get('BitFacet');

// изменились эти товары — в журнал правок (видно со следующего запроса)
$bf->queueChanged([15, 16, 42]);

// изменилось всё (большой импорт) — индексы пометить устаревшими и пересобрать
$bf->queueStale();

Очередь обрабатывается в конце запроса (в php-fpm — после ответа посетителю). Пересобрать набор сразу:

$info = $modx->services->get('BitFacet')->updater('catalog')->rebuild();
// ['n' => товаров, 'vn' => модификаций, …] или null, если сборка уже идёт

Запрос к индексу из PHP

Индекс можно использовать и без сниппета — например, для блока «Похожие товары» или своего API:

use BitFacet\Index\Query;

$index = $modx->services->get('BitFacet')->store('catalog')->open();
$res = (new Query($index))->run([
    'maps'    => ['live'],                              // только опубликованные
    'base'    => ['section' => [5]],                    // раздел 5 с подразделами
    'filters' => ['ms:color' => ['красный', 'синий'],   // ИЛИ внутри фильтра, И между фильтрами
                  'ms:vendor' => ['nike']],
    'ranges'  => ['ms:price' => [1000, null]],          // от 1000, без верхней границы
    'counts'  => ['ms:size'],                           // счётчики значений
    'stats'   => ['ms:price'],                          // min/max
    'sort'    => 'price', 'dir' => 'asc',
    'limit'   => 12, 'offset' => 0,
]);
// $res['total'], $res['ids'], $res['counts']['ms:size'] = [значение => число], $res['stats']['ms:price']

Значения в filters — ключи индекса: как на вкладке «Значения» (в нижнем регистре).

Где что лежит

core/components/bitfacet/
    data/sets/        наборы фильтров (*.json)
    data/index/       индексы, журнал ошибок, сокет турбо
    src/Index/        ядро: битовые карты, сборка, запросы
    src/Provider/     источники: ресурсы, TV, MiniShop3, свои таблицы
    src/Front/        фильтр на сайте и турборежим
    cli/rebuild.php   пересборка из консоли и крона
    cli/turbo.php     процесс турборежима
assets/components/bitfacet/
    js/web/bitfacet.js        фильтр без перезагрузки
    publicConnector.php       эндпоинт фильтра