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

# OQL Overview

> OneTest Query Language for powerful test searches

**OQL (OneTest Query Language)** is a simple, powerful way to search and filter tests. It's inspired by JQL (Jira Query Language) and designed to feel natural while giving you precise control.

## Why Use OQL?

<CardGroup cols={2}>
  <Card title="Precise Control" icon="crosshairs">
    Filter by exact criteria, not fuzzy matches
  </Card>

  <Card title="Save Queries" icon="bookmark">
    Save complex searches for reuse
  </Card>

  <Card title="Combine Conditions" icon="layer-group">
    Use AND, OR, NOT for complex filters
  </Card>

  <Card title="Fast & Efficient" icon="bolt">
    Optimized queries execute instantly
  </Card>
</CardGroup>

## Quick Examples

<CodeGroup>
  ```oql Simple Filter theme={null}
  status = active
  ```

  ```oql Multiple Conditions theme={null}
  status = active AND priority IN (p1, p2)
  ```

  ```oql Pattern Matching theme={null}
  title ~ "login" AND scope ^ "auth"
  ```

  ```oql Date Queries theme={null}
  created_at >= -7d ORDER BY created_at DESC
  ```

  ```oql Arrays theme={null}
  tags CONTAINS "smoke" AND tags NOT CONTAINS "deprecated"
  ```
</CodeGroup>

## Basic Syntax

<Tabs>
  <Tab title="Comparisons">
    Compare fields to values:

    | Operator | Meaning          | Example                   |
    | -------- | ---------------- | ------------------------- |
    | `=`      | Equals           | `status = active`         |
    | `!=`     | Not equals       | `priority != p4`          |
    | `>`      | Greater than     | `created_at > 2024-01-01` |
    | `>=`     | Greater or equal | `version >= 2.0`          |
    | `<`      | Less than        | `priority < p2`           |
    | `<=`     | Less or equal    | `updated_at <= -7d`       |
  </Tab>

  <Tab title="Pattern Matching">
    Match text patterns:

    | Operator | Meaning      | Example                       |
    | -------- | ------------ | ----------------------------- |
    | `~`      | Contains     | `title ~ "login"`             |
    | `^ `     | Starts with  | `identifier ^ "TC-10"`        |
    | `$`      | Ends with    | `title $ "test"`              |
    | `!~`     | Not contains | `description !~ "deprecated"` |
  </Tab>

  <Tab title="Arrays">
    Work with lists:

    | Operator       | Meaning                   | Example                                 |
    | -------------- | ------------------------- | --------------------------------------- |
    | `IN`           | Value in list             | `priority IN (p1, p2)`                  |
    | `NOT IN`       | Value not in list         | `status NOT IN (archived, deleted)`     |
    | `CONTAINS`     | Array contains value      | `tags CONTAINS "smoke"`                 |
    | `CONTAINS ANY` | Array contains any value  | `tags CONTAINS ANY (smoke, regression)` |
    | `CONTAINS ALL` | Array contains all values | `tags CONTAINS ALL (smoke, critical)`   |
  </Tab>

  <Tab title="Logic">
    Combine conditions:

    | Operator | Meaning          | Example                                                    |
    | -------- | ---------------- | ---------------------------------------------------------- |
    | `AND`    | Both conditions  | `status = active AND priority = p1`                        |
    | `OR`     | Either condition | `priority = p1 OR priority = p2`                           |
    | `NOT`    | Negate condition | `NOT status = archived`                                    |
    | `( )`    | Group conditions | `(status = active OR status = approved) AND priority = p1` |
  </Tab>
</Tabs>

## Common Queries

<AccordionGroup>
  <Accordion title="Find Failed Tests" icon="triangle-exclamation">
    ```oql theme={null}
    status = failed AND last_run >= -7d
    ```

    Find tests that failed in the last 7 days.
  </Accordion>

  <Accordion title="Smoke Tests" icon="fire">
    ```oql theme={null}
    tags CONTAINS "smoke" AND status = active
    ORDER BY priority
    ```

    All active smoke tests, ordered by priority.
  </Accordion>

  <Accordion title="High Priority Tests" icon="exclamation">
    ```oql theme={null}
    priority IN (p0, p1) AND status != archived
    ORDER BY created_at DESC
    ```

    All P0 and P1 tests that aren't archived.
  </Accordion>

  <Accordion title="Recently Updated" icon="clock">
    ```oql theme={null}
    updated_at >= -14d
    ORDER BY updated_at DESC
    LIMIT 50
    ```

    Tests updated in the last 2 weeks.
  </Accordion>

  <Accordion title="Never Run" icon="circle-xmark">
    ```oql theme={null}
    last_run IS NULL AND status = active
    ```

    Active tests that have never been executed.
  </Accordion>

  <Accordion title="Specific Feature" icon="folder">
    ```oql theme={null}
    folder_path ~ "/authentication/" AND
    (tags CONTAINS "smoke" OR priority = p1)
    ```

    Important authentication tests.
  </Accordion>
</AccordionGroup>

## Date & Time Queries

OQL supports flexible date queries:

<Tabs>
  <Tab title="Relative Dates">
    ```oql theme={null}
    created_at >= -7d        # Last 7 days
    created_at >= -2w        # Last 2 weeks
    created_at >= -3M        # Last 3 months
    created_at >= -1y        # Last year
    ```
  </Tab>

  <Tab title="Specific Dates">
    ```oql theme={null}
    created_at >= 2024-01-01
    created_at BETWEEN 2024-01-01 AND 2024-12-31
    updated_at = 2024-06-15
    ```
  </Tab>

  <Tab title="Date Functions">
    ```oql theme={null}
    created_at >= startOfWeek()
    created_at >= startOfMonth()
    created_at >= startOfYear()
    created_at <= endOfMonth()
    ```
  </Tab>

  <Tab title="Time Comparisons">
    ```oql theme={null}
    updated_at > created_at
    last_run >= updated_at
    ```
  </Tab>
</Tabs>

## Sorting & Pagination

Control result order and size:

```oql theme={null}
# Sort by single field
ORDER BY created_at DESC

# Sort by multiple fields
ORDER BY priority ASC, created_at DESC

# Limit results
LIMIT 50

# Pagination
LIMIT 50 OFFSET 100
```

## Saved Queries

Save frequently-used queries:

<Steps>
  <Step title="Write Your Query">
    ```oql theme={null}
    priority IN (p0, p1) AND status = active AND tags CONTAINS "smoke"
    ```
  </Step>

  <Step title="Save with Name">
    Click "Save Query" and give it a name:

    ```
    Critical Smoke Tests
    ```
  </Step>

  <Step title="Reuse Anytime">
    Access from the "Saved Queries" dropdown
  </Step>
</Steps>

## Using with AI

<Tip>
  You don't need to write OQL manually! Just ask the AI:

  ```
  Show me high priority tests that failed recently
  ```

  The AI translates to:

  ```oql theme={null}
  priority IN (p0, p1) AND status = failed AND last_run >= -7d
  ```
</Tip>

## What's Next?

<CardGroup cols={2}>
  <Card title="Full Syntax Reference" icon="code" href="/oql/syntax">
    Complete OQL syntax documentation
  </Card>

  <Card title="Query Examples" icon="lightbulb" href="/oql/examples">
    More real-world query examples
  </Card>

  <Card title="Field Reference" icon="list" href="/oql/field-reference">
    All searchable fields
  </Card>

  <Card title="AI Search" icon="robot" href="/ai/search-tests">
    Let AI write queries for you
  </Card>
</CardGroup>