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

# Run Queries

> Run your first queries on ParadeDB

Now that your [environment is configured](/documentation/getting-started/environment), select the codetab for your tool and run some queries.

## Match Query

We're now ready to execute a basic text search query. We'll look for matches where `description` matches `running shoes` where `rating` is greater than `2`.

<CodeGroup>
  ```sql SQL theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE description ||| 'running shoes' AND rating > 2
  ORDER BY rating
  LIMIT 5;
  ```

  ```ts Drizzle theme={null}
  import { and, gt } from "drizzle-orm";
  import { search } from "@paradedb/drizzle-paradedb";

  await db
    .select({
      description: mockItems.description,
      rating: mockItems.rating,
      category: mockItems.category,
    })
    .from(mockItems)
    .where(
      and(
        search.matchAny(mockItems.description, "running shoes"),
        gt(mockItems.rating, 2),
      ),
    )
    .orderBy(mockItems.rating)
    .limit(5);
  ```

  ```python Django theme={null}
  from paradedb import MatchAny, ParadeDB

  MockItem.objects.filter(
      description=ParadeDB(MatchAny('running shoes')),
      rating__gt=2
  ).values('description', 'rating', 'category').order_by('rating')[:5]
  ```

  ```python SQLAlchemy theme={null}
  from sqlalchemy import select
  from sqlalchemy.orm import Session
  from paradedb.sqlalchemy import search

  stmt = (
      select(MockItem.description, MockItem.rating, MockItem.category)
      .where(search.match_any(MockItem.description, "running shoes"), MockItem.rating > 2)
      .order_by(MockItem.rating)
      .limit(5)
  )

  with Session(engine) as session:
      session.execute(stmt).all()
  ```

  ```ruby Rails theme={null}
  MockItem.search(:description)
          .matching_any("running shoes")
          .where(rating: 3..)
          .select(:description, :rating, :category)
          .order(:rating)
          .limit(5)
  ```

  ```cs EF Core theme={null}
  await dbContext
      .MockItems.Where(item =>
          EF.Functions.MatchAny(item.Description, "running shoes") && item.Rating > 2
      )
      .OrderBy(item => item.Rating)
      .Select(item => new { item.Description, item.Rating, item.Category })
      .Take(5)
      .ToListAsync();
  ```
</CodeGroup>

```ini Expected Response theme={null}
     description     | rating | category
---------------------+--------+----------
 White jogging shoes |      3 | Footwear
 Generic shoes       |      4 | Footwear
 Sleek running shoes |      5 | Footwear
(3 rows)
```

`|||` is ParadeDB's custom [match disjunction](/documentation/full-text/match#disjunction) operator, which means "find me all documents containing
`running OR shoes`.

If we want all documents containing `running AND shoes`, we can use ParadeDB's `&&&` [match conjunction](/documentation/full-text/match#conjunction) operator.

<CodeGroup>
  ```sql SQL theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE description &&& 'running shoes' AND rating > 2
  ORDER BY rating
  LIMIT 5;
  ```

  ```ts Drizzle theme={null}
  import { and, gt } from "drizzle-orm";
  import { search } from "@paradedb/drizzle-paradedb";

  await db
    .select({
      description: mockItems.description,
      rating: mockItems.rating,
      category: mockItems.category,
    })
    .from(mockItems)
    .where(
      and(
        search.matchAll(mockItems.description, "running shoes"),
        gt(mockItems.rating, 2),
      ),
    )
    .orderBy(mockItems.rating)
    .limit(5);
  ```

  ```python Django theme={null}
  from paradedb import MatchAll, ParadeDB

  MockItem.objects.filter(
      description=ParadeDB(MatchAll('running shoes')),
      rating__gt=2
  ).values('description', 'rating', 'category').order_by('rating')[:5]
  ```

  ```python SQLAlchemy theme={null}
  from sqlalchemy import select
  from sqlalchemy.orm import Session
  from paradedb.sqlalchemy import search

  stmt = (
      select(MockItem.description, MockItem.rating, MockItem.category)
      .where(search.match_all(MockItem.description, "running shoes"), MockItem.rating > 2)
      .order_by(MockItem.rating)
      .limit(5)
  )

  with Session(engine) as session:
      session.execute(stmt).all()
  ```

  ```ruby Rails theme={null}
  MockItem.search(:description)
          .matching_all("running shoes")
          .where(rating: 3..)
          .select(:description, :rating, :category)
          .order(:rating)
          .limit(5)
  ```

  ```cs EF Core theme={null}
  await dbContext
      .MockItems.Where(item =>
          EF.Functions.MatchAll(item.Description, "running shoes") && item.Rating > 2
      )
      .OrderBy(item => item.Rating)
      .Select(item => new { item.Description, item.Rating, item.Category })
      .Take(5)
      .ToListAsync();
  ```
</CodeGroup>

```ini Expected Response theme={null}
     description     | rating | category
---------------------+--------+----------
 Sleek running shoes |      5 | Footwear
(1 row)
```

## BM25 Scoring

Next, let's add [BM25 scoring](/documentation/sorting/score) to the results, which sorts matches by relevance. To do this, we'll use `pdb.score`.

<CodeGroup>
  ```sql SQL theme={null}
  SELECT description, pdb.score(id)
  FROM mock_items
  WHERE description ||| 'running shoes' AND rating > 2
  ORDER BY score DESC
  LIMIT 5;
  ```

  ```ts Drizzle theme={null}
  import { and, desc, gt } from "drizzle-orm";
  import { search } from "@paradedb/drizzle-paradedb";

  await db
    .select({
      description: mockItems.description,
      score: search.score(mockItems.id),
    })
    .from(mockItems)
    .where(
      and(
        search.matchAny(mockItems.description, "running shoes"),
        gt(mockItems.rating, 2),
      ),
    )
    .orderBy(desc(search.score(mockItems.id)))
    .limit(5);
  ```

  ```python Django theme={null}
  from paradedb import MatchAny, ParadeDB, Score

  MockItem.objects.filter(
      description=ParadeDB(MatchAny('running shoes')),
      rating__gt=2
  ).annotate(
      score=Score()
  ).values('description', 'score').order_by('-score')[:5]
  ```

  ```python SQLAlchemy theme={null}
  from sqlalchemy import desc, select
  from sqlalchemy.orm import Session
  from paradedb.sqlalchemy import pdb, search

  stmt = (
      select(MockItem.description, pdb.score(MockItem.id).label("score"))
      .where(search.match_any(MockItem.description, "running shoes"), MockItem.rating > 2)
      .order_by(desc("score"))
      .limit(5)
  )

  with Session(engine) as session:
      session.execute(stmt).all()
  ```

  ```ruby Rails theme={null}
  MockItem.search(:description)
          .matching_any("running shoes")
          .where(rating: 3..)
          .with_score
          .select(:description)
          .order(search_score: :desc)
          .limit(5)
  ```

  ```cs EF Core theme={null}
  await dbContext
      .MockItems.Where(item =>
          EF.Functions.MatchAny(item.Description, "running shoes") && item.Rating > 2
      )
      .Select(item => new { item.Description, Score = EF.Functions.Score(item.Id) })
      .OrderByDescending(item => item.Score)
      .Take(5)
      .ToListAsync();
  ```
</CodeGroup>

```ini Expected Response theme={null}
     description     |   score
---------------------+-----------
 Sleek running shoes |  6.817111
 Generic shoes       | 3.8772602
 White jogging shoes | 3.4849067
(3 rows)
```

## Highlighting

Finally, let's also [highlight](/documentation/full-text/highlight) the relevant portions of the documents that were matched.
To do this, we'll use `pdb.snippet`.

<CodeGroup>
  ```sql SQL theme={null}
  SELECT description, pdb.snippet(description), pdb.score(id)
  FROM mock_items
  WHERE description ||| 'running shoes' AND rating > 2
  ORDER BY score DESC
  LIMIT 5;
  ```

  ```ts Drizzle theme={null}
  import { and, desc, gt } from "drizzle-orm";
  import { search } from "@paradedb/drizzle-paradedb";

  await db
    .select({
      description: mockItems.description,
      snippet: search.snippet(mockItems.description),
      score: search.score(mockItems.id),
    })
    .from(mockItems)
    .where(
      and(
        search.matchAny(mockItems.description, "running shoes"),
        gt(mockItems.rating, 2),
      ),
    )
    .orderBy(desc(search.score(mockItems.id)))
    .limit(5);
  ```

  ```python Django theme={null}
  from paradedb import MatchAny, ParadeDB, Score, Snippet

  MockItem.objects.filter(
      description=ParadeDB(MatchAny('running shoes')),
      rating__gt=2
  ).annotate(
      snippet=Snippet('description'),
      score=Score()
  ).values('description', 'snippet', 'score').order_by('-score')[:5]
  ```

  ```python SQLAlchemy theme={null}
  from sqlalchemy import desc, select
  from sqlalchemy.orm import Session
  from paradedb.sqlalchemy import pdb, search

  stmt = (
      select(
          MockItem.description,
          pdb.snippet(MockItem.description).label("snippet"),
          pdb.score(MockItem.id).label("score"),
      )
      .where(search.match_any(MockItem.description, "running shoes"), MockItem.rating > 2)
      .order_by(desc("score"))
      .limit(5)
  )

  with Session(engine) as session:
      session.execute(stmt).all()
  ```

  ```ruby Rails theme={null}
  MockItem.search(:description)
          .matching_any("running shoes")
          .where(rating: 3..)
          .with_snippet(:description)
          .with_score
          .select(:description)
          .order(search_score: :desc)
          .limit(5)
  ```

  ```cs EF Core theme={null}
  await dbContext
      .MockItems.Where(item =>
          EF.Functions.MatchAny(item.Description, "running shoes") && item.Rating > 2
      )
      .Select(item => new
      {
          item.Description,
          Snippet = EF.Functions.Snippet(item.Description),
          Score = EF.Functions.Score(item.Id)
      })
      .OrderByDescending(item => item.Score)
      .Take(5)
      .ToListAsync();
  ```
</CodeGroup>

```ini Expected Response theme={null}
     description     |              snippet              |   score
---------------------+-----------------------------------+-----------
 Sleek running shoes | Sleek <b>running</b> <b>shoes</b> |  6.817111
 Generic shoes       | Generic <b>shoes</b>              | 3.8772602
 White jogging shoes | White jogging <b>shoes</b>        | 3.4849067
(3 rows)
```

## Top K

ParadeDB is highly optimized for quickly returning the [Top K](/documentation/sorting/topk) results out of the index. In SQL, this means queries that contain an `ORDER BY...LIMIT`:

<CodeGroup>
  ```sql SQL theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE description ||| 'running shoes'
  ORDER BY rating
  LIMIT 5;
  ```

  ```ts Drizzle theme={null}
  import { search } from "@paradedb/drizzle-paradedb";

  await db
    .select({
      description: mockItems.description,
      rating: mockItems.rating,
      category: mockItems.category,
    })
    .from(mockItems)
    .where(search.matchAny(mockItems.description, "running shoes"))
    .orderBy(mockItems.rating)
    .limit(5);
  ```

  ```python Django theme={null}
  from paradedb import MatchAny, ParadeDB

  MockItem.objects.filter(
      description=ParadeDB(MatchAny('running shoes'))
  ).values('description', 'rating', 'category').order_by('rating')[:5]
  ```

  ```python SQLAlchemy theme={null}
  from sqlalchemy import select
  from sqlalchemy.orm import Session
  from paradedb.sqlalchemy import search

  stmt = (
      select(MockItem.description, MockItem.rating, MockItem.category)
      .where(search.match_any(MockItem.description, "running shoes"))
      .order_by(MockItem.rating)
      .limit(5)
  )

  with Session(engine) as session:
      session.execute(stmt).all()
  ```

  ```ruby Rails theme={null}
  MockItem.search(:description)
          .matching_any("running shoes")
          .select(:description, :rating, :category)
          .order(:rating)
          .limit(5)
  ```

  ```cs EF Core theme={null}
  await dbContext
      .MockItems.Where(item => EF.Functions.MatchAny(item.Description, "running shoes"))
      .OrderBy(item => item.Rating)
      .Select(item => new { item.Description, item.Rating, item.Category })
      .Take(5)
      .ToListAsync();
  ```
</CodeGroup>

```ini Expected Response theme={null}
     description     | rating | category
---------------------+--------+----------
 White jogging shoes |      3 | Footwear
 Generic shoes       |      4 | Footwear
 Sleek running shoes |      5 | Footwear
(3 rows)
```

## Facets

[Faceted queries](/documentation/aggregates/facets) allow a single query to return both the Top K results and an aggregate value,
which is more CPU-efficient than issuing two separate queries.

For example, the following query returns the top 3 results as well as the total number of results matched.

<CodeGroup>
  ```sql SQL theme={null}
  SELECT
       description, rating, category,
       pdb.agg('{"value_count": {"field": "id"}}') OVER ()
  FROM mock_items
  WHERE description ||| 'running shoes'
  ORDER BY rating
  LIMIT 5;
  ```

  ```ts Drizzle theme={null}
  import { search } from "@paradedb/drizzle-paradedb";

  await db
    .select({
      description: mockItems.description,
      rating: mockItems.rating,
      category: mockItems.category,
      agg: search.agg({ value_count: { field: "id" } }).over(),
    })
    .from(mockItems)
    .where(search.matchAny(mockItems.description, "running shoes"))
    .orderBy(mockItems.rating)
    .limit(5);
  ```

  ```python Django theme={null}
  from paradedb import MatchAny, ParadeDB

  (
      MockItem.objects
      .filter(description=ParadeDB(MatchAny('running shoes')))
      .order_by('rating')
      .values('description', 'rating', 'category')[:5]
      .facets(agg='{"value_count": {"field": "id"}}')
  )
  ```

  ```python SQLAlchemy theme={null}
  from sqlalchemy import select
  from sqlalchemy.orm import Session
  from paradedb.sqlalchemy import facets, search

  base = (
      select(MockItem.description, MockItem.rating, MockItem.category)
      .where(search.match_any(MockItem.description, "running shoes"))
      .order_by(MockItem.rating)
      .limit(5)
  )

  stmt = facets.with_rows(base, agg=facets.value_count(field="id"), key_field=MockItem.id)

  with Session(engine) as session:
      rows = session.execute(stmt).all()
      facets.extract(rows)
  ```

  ```ruby Rails theme={null}
  relation = MockItem.search(:description)
                     .matching_any("running shoes")
                     .with_agg(agg: ParadeDB::Aggregations.value_count(:id))
                     .order(:rating)
                     .select(:description, :rating, :category)
                     .limit(5)

  rows = relation.to_a
  facets = relation.aggregates
  ```

  ```cs EF Core theme={null}
  await dbContext
      .MockItems.Where(item => EF.Functions.MatchAny(item.Description, "running shoes"))
      .OrderBy(item => item.Rating)
      .Select(item => new
      {
          item.Description,
          item.Rating,
          item.Category,
          Agg = EF.Functions.AggOver(new { value_count = new { field = "id" } })
      })
      .Take(5)
      .ToListAsync();
  ```
</CodeGroup>

```ini Expected Response theme={null}
     description     | rating | category |      agg
---------------------+--------+----------+----------------
 White jogging shoes |      3 | Footwear | {"value": 3.0}
 Generic shoes       |      4 | Footwear | {"value": 3.0}
 Sleek running shoes |      5 | Footwear | {"value": 3.0}
(3 rows)
```

That's it! Next, let's [load your data](/documentation/getting-started/load) to start running real queries.