From d1d654ebac2d51e3841675faeb56480e440f622f Mon Sep 17 00:00:00 2001
From: Wolfgang Müller
Date: Tue, 5 Mar 2024 18:08:09 +0100
Subject: Initial commit

---
 docs/usage/filtering.rst | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 docs/usage/filtering.rst

(limited to 'docs/usage/filtering.rst')

diff --git a/docs/usage/filtering.rst b/docs/usage/filtering.rst
new file mode 100644
index 0000000..05066fb
--- /dev/null
+++ b/docs/usage/filtering.rst
@@ -0,0 +1,45 @@
+Filtering
+=========
+
+A filter is a combination of predicates that have to be satisfied. **hircine**
+provides a filter interface that allows using almost any type of metadata as a
+predicate and can therefore build complex and expressive queries.
+
+.. image:: /_images/filtering.jpg
+   :align: center
+   :alt: Filtering comics
+
+If given multiple types of predicates, all of them have to match. If one type
+of predicate contains multiple selections, the selected mode determines how
+they are combined:
+
++----------------------+--------------------------------------------------+
+| Mode                 | Behaviour                                        |
++======================+==================================================+
+| ∀ ("for all")        | matches if all given entities match              |
++----------------------+--------------------------------------------------+
+| ∃ ("there exists")   | matches if any of the given entities match       |
++----------------------+--------------------------------------------------+
+| = ("exactly")        | matches if entities are present exactly as given |
++----------------------+--------------------------------------------------+
+
+For example, in the picture above, a comic only matches if *all* of the
+following is true:
+
+- It is tagged as ``female:idol`` or ``:tights``.
+- It is tagged with the artist ``40hara``.
+- It is rated as *Questionable*.
+- It is uncensored.
+- It is in any language except Japanese.
+
+Matching empty sets
+-------------------
+
+Each type of predicate may also match on the ∅ empty set. If enabled, the
+predicate only matches if the object does not contain any entities of that
+type.
+
+.. important::
+
+   If matching on the empty set, make sure there are no selections present in
+   the corresponding dropdown menu, as otherwise the filter will never match.
-- 
cgit v1.2.3-2-gb3c3