> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wesog.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Filters

> Create a boolean formula combining several filters and subfilters.

The `q` url parameter of the search endpoint (`GET /imgs`) defines the **query filtering formula**. This parameter uses a special syntax that allows various filter combinations using boolean operators and supports subfilters for more granular searches.

## Filter Syntax

Filters form the fundamental component of the query filtering formula. They adhere to the syntax outlined below:

<CodeGroup>
  ```
  <filter acronym><filter operator><filter value>
  ```
</CodeGroup>

<CardGroup cols={3}>
  <Card title="Filter Acronym" icon="tag">
    Multiple acronyms can refer to the same filter

    Example: `k`, `key`, `keywords`
  </Card>

  <Card title="Filter Operator" icon="equals">
    Defines how the filter is applied

    Example: `=`, `~`, `>`, `<`
  </Card>

  <Card title="Filter Value" icon="input-text">
    The actual search criteria

    Example: `"sunset"`, `2024-01-01`
  </Card>
</CardGroup>

### Filter acronym

Each filter can be identified by multiple acronyms. For example, the **keyword** filter can be referred to by the following acronyms: `k`, `key`, `keywords`.

### Filter Operators

<AccordionGroup>
  <Accordion title="Similarity Operators">
    * `~`: Similar (AI semantic search for text/image, subword search for others)
    * `~~`: Very similar
    * `~~~`: Super similar
  </Accordion>

  <Accordion title="Equality Operators">
    * `=`: Equal
    * `==`: Very equal
    * `===`: Super equal
    * `====`: Exact duplicate. The most precise duplicate-detection mode available, slightly slower than `=`, `==` or `===`. Currently available only to selected tenants.
  </Accordion>

  <Accordion title="Range Comparison">
    For numeric filters, dates, and alphabetical order:

    * `<`: Less than
    * `>`: Greater than
    * `<=`: Less or equal than (Aliases: `=<`, `≤`)
    * `>=`: Greater or equal than (Aliases: `=<`, `≥`)
  </Accordion>

  <Accordion title="Set Comparison">
    * `=`: Must contain all of them
    * `∩`: Must contain at least one of them (Intersection)
  </Accordion>
</AccordionGroup>

### Filter Values

<Note>
  Each filter has a specific format for its values. Here are common examples:
</Note>

<CodeGroup>
  ```text Date Format theme={null}
  YEAR-MONTH-DAY
  Example: d=2005-5-13
  ```

  ```text Keywords theme={null}
  Comma separated values
  Example: k=blue, sky
  ```

  ```text Location theme={null}
  Single string value
  Example: city=Paris
  ```
</CodeGroup>

## Available Filters and Subfilters

List of available filters and subfilters along with their prefixes:

| Filter                   | Available Acronyms     | Available Operators                        | Value format    | Examples         |
| ------------------------ | ---------------------- | ------------------------------------------ | --------------- | ---------------- |
| **T**ext                 | `t`, `txt`, `text`     | `~`, `~~`, `~~~`                           | Free text       | `t~a red car`    |
| **I**mage                | `i`, `img`, `image`    | `=`, `==`, `===`, `====`, `~`, `~~`, `~~~` | Image reference | `i~123456`       |
| **P**erson               | `p`,        `person`   | `~`, `~~`, `~~~`                           | ImgRef\_faceNum | `p=taylor swift` |
| **D**ate                 | `d`,        `date`     | `=`, `<`, `>`, `<=`, `>=`                  | YEAR-MONTH-DAY  | `d>2020-01-01`   |
| **ID**                   | `id`                   | `=`, `<`, `>`, `<=`, `>=`, `∩`             | Numeric         | `id=1234`        |
| Aspect **R**atio         | `r`,        `ratio`    | `=`, `<`, `>`, `<=`, `>=`, `∩`             | Numeric         | `r<1.5`          |
| **N**um of people        | `n`,        `n_people` | `=`, `<`, `>`, `<=`, `>=`, `∩`             | Numeric         | `n=3`            |
| **AI** generated         | `ai`                   | `=`                                        | Boolean         | `ai=true`        |
| **M**odel **R**elease    | `mr`                   | `=`                                        | Boolean         |                  |
| **P**roperty **R**elease | `pr`                   | `=`                                        | Boolean         |                  |
| **NSFW**                 | `nsfw`                 | `=`                                        | Boolean         | `nsfw=false`     |
| **O**rientation          | `o`, `orientation`     | `=`                                        | String          | `o=Horizontal`   |
| Status                   | `status`               | `=`                                        | String          | `status=Active`  |
| **A**uthor               | `a`, `author`          | `=`                                        | String          |                  |
| Provider                 | `provider`             | `=`                                        | String          |                  |
| Event                    | `e`, `event`           | `=`                                        | String          |                  |
| City                     | `city`                 | `=`                                        | String          |                  |
| Country                  | `country`              | `=`                                        | String          |                  |
| **L**ocation             | `l`, `location`        | `=`                                        | String          |                  |
| **S**hot                 | `s`, `shot`            | `=`                                        | String          |                  |
| Scene                    | `scene`                | `=`                                        | String          |                  |
| **M**edium level **1**   | `m1`                   | `=`                                        | String          |                  |
| **M**edium level **2**   | `m2`, `medium`         | `=`                                        | String          |                  |
| **M**edium level **3**   | `m3`, `technique`      | `=`                                        | String          |                  |
| **K**eywords             | `k`, `keywords`        | `=`, `∩`                                   | Comma separated |                  |
| Categories               | `categories`           | `=`, `∩`                                   | Comma separated |                  |
| Collections              | `collections`          | `=`, `∩`                                   | Comma separated |                  |
| **C**olor                | `c`, `color`           | `=`                                        | Color           | `c=#ff0000`      |

**Quick Examples:**

<CardGroup cols={2}>
  <Card title="Semantic Search" icon="brain">
    `t~us elections` - Finds images semantically similar to "us elections"
  </Card>

  <Card title="Exact Search" icon="magnifying-glass">
    `t=us elections` - Finds images containing exact text "us elections"
  </Card>

  <Card title="Keyword Search" icon="tag">
    `k=us elections` - Finds images tagged with "us elections"
  </Card>

  <Card title="Date Range" icon="calendar">
    `d>2020-03-11` - Finds photographs after March 11, 2020
  </Card>
</CardGroup>

## Duplicate Verification Response (`i====`)

When a query uses the `====` operator, the response is a normal search response (`results`, `count`, `facets`), but adjusted to reflect that `====` only verifies the single best match:

* If a duplicate version is detected, it will be indicated in `results`; in that case, `count` is 1.
* If it is **not** confirmed as a duplicate, or verification could not be completed, `results` is empty, `count` is `0`, and `facets` is empty.

## Filter with subfilters

<Warning>Subfilters are not ready yet. They will be available in future releases of Wesog Search.</Warning>

Some filters (image `i`, person `p`, author `a`) can have subfilters. Subfilter specifies further properties of a filter. Subfilters are defined after the filter containing the "subfilter query formula" between square brackets.

**Examples:**

* `p=taylor swift[a=20]` search for pictures of Talyor swift at the age of 20 years old.
* `p=taylor swift[t=green dress and cowboy boots]` search for pictures of Talyor swift with that clothes.
* `p=donald trump[k=smiling k=lookingToCamera]` search for pictures of Donald Trump smiling, looking to camera.
* `p=anyone[a>80]` search for pictures of any celebrity with more than 80 years old.
* `a=anyone[g=woman && a>70]` search for pictures done by women (women photographer or painters).
* `i=1234[t=at winter]`. Considering 1234 the id of a previusly upluaded photo of the stockholm skyline at summer. Ssearch for pictures of Stockholm at Winter
* \`\`

## Boolean Operators

<Tip>
  You can combine filters using Boolean logic to create complex search queries.
</Tip>

<CardGroup cols={3}>
  <Card title="AND Operator" icon="ampersand">
    `&&` - Both conditions must be true

    Example: `t=beach && c=blue`
  </Card>

  <Card title="OR Operator" icon="bars">
    `||` - Either condition can be true

    Example: `t=beach || t=mountain`
  </Card>

  <Card title="NOT Operator" icon="x">
    `!` - Excludes the condition

    Example: `t=beach && !c=blue`
  </Card>
</CardGroup>

<Note>
  Use parentheses `()` to group filters and control the order of operations.
</Note>

## Advanced Query Examples

<AccordionGroup>
  <Accordion title="Basic Text and Color Search">
    **Query:** `t=beach && c=blue`

    **Description:** Search for images of beaches **and** the color blue.
  </Accordion>

  <Accordion title="Multiple Options with Exclusion">
    **Query:** `(t=cats || t=dogs) && !m=bw_photo`

    **Description:** Search for images of cats or dogs, excluding black and white images.
  </Accordion>

  <Accordion title="Celebrity with Age and Location">
    **Query:** `p=barack obama[a≥40 && a≤50] && l=Washington D.C.`

    **Description:** Search for images of Barack Obama aged between 40 and 50, taken in Washington D.C.
  </Accordion>

  <Accordion title="Anonymous Person Demographics">
    **Query:** `p=anyone[g=female && a≥30 && a≤40 && (k=smiling || k=wearing glasses)]`

    **Description:** Search for images of anonymous females aged 30-40, who are smiling or wearing glasses.
  </Accordion>

  <Accordion title="Celebrity Performance with Color">
    **Query:** `( p=taylor swift[t=performing] || p=selena gomez[t=performing] ) && c=red`

    **Description:** Search for images of Taylor Swift or Selena Gomez performing on stage, featuring the color red.
  </Accordion>

  <Accordion title="Location-based Architecture Search">
    **Query:** `(l=Paris || l=London) && k=gothic architecture`

    **Description:** Search for images taken in Paris or London of buildings with Gothic architecture.
  </Accordion>

  <Accordion title="Similar Image with Modifications">
    **Query:** `i=54321[t=sunset] && n=0`

    **Description:** Search for images similar to image REF 54321 with a "sunset" modification, excluding images with people.
  </Accordion>

  <Accordion title="Activity-based Demographics">
    **Query:** `p=anyone[g=male && a≥30 && a≤40 && (t=running || t=jumping)] && l=New York City`

    **Description:** Search for images of anonymous males aged 30-40, running or jumping, taken in New York City.
  </Accordion>

  <Accordion title="Aspect Ratio with Scene and Date">
    **Query:** `r=16:9 && t=beach && t=sunset && d=2020-*-*`

    **Description:** Search for 16:9 aspect ratio images of beaches at sunset, taken in 2020.
  </Accordion>

  <Accordion title="Multiple Criteria Combination">
    **Query:** `k=nature && (m=photograph || m=illustration) && r:4:3`

    **Description:** Search for images with the keyword "nature," medium type "photograph" or "illustration," and aspect ratio 4:3.
  </Accordion>
</AccordionGroup>