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

# Product catalog with Query and Search

> Read only the products you need from a private silo, using URL parameters.

This example stores a small product catalog in a private silo and shows how to read parts of it without downloading the whole thing.

**You will use:** a [private silo](https://docs.jsonsilo.com/silo-types/private-silo.md), an [Access Key](https://docs.jsonsilo.com/keys/access-keys.md), [Query](https://docs.jsonsilo.com/features/query-silo-data.md), and [Search](https://docs.jsonsilo.com/features/search-silo-data.md).

## The data

Create a **Private** silo named `catalog` with this JSON. Search works on a top-level array, so the products are the root of the document.

```json catalog.json theme={null}
[
  {
    "id": 1,
    "name": "Classic Mug",
    "category": "kitchen",
    "price": 12.5,
    "tags": [{ "label": "ceramic" }, { "label": "gift" }]
  },
  {
    "id": 2,
    "name": "Canvas Tote",
    "category": "bags",
    "price": 18,
    "tags": [{ "label": "cotton" }]
  },
  {
    "id": 3,
    "name": "Travel Mug",
    "category": "kitchen",
    "price": 24,
    "tags": [{ "label": "steel" }, { "label": "gift" }]
  },
  {
    "id": 4,
    "name": "Leather Backpack",
    "category": "bags",
    "price": 89,
    "tags": [{ "label": "leather" }]
  }
]
```

Every request below goes to your silo URL with your Access Key:

```bash Terminal theme={null}
curl -H 'X-SILO-KEY: <YOUR_X_SILO_KEY_HERE>' \
  'https://[region-code].jsonsilo.com/[file-uuid]?<PARAMETERS>'
```

## Recipes

> [accordion] Get one product by position
>
> `idx` picks one item from the array, counting from `0`.
>
> ```bash theme={null}
> ?idx=2
> ```
>
> ```json Response theme={null}
> {
>   "id": 3,
>   "name": "Travel Mug",
>   "category": "kitchen",
>   "price": 24,
>   "tags": [{ "label": "steel" }, { "label": "gift" }]
> }
> ```

> [accordion] Get one field of one product
>
> Add `path` to `idx` to read a single field.
>
> ```bash theme={null}
> ?idx=0&path=name
> ```
>
> ```json Response theme={null}
> "Classic Mug"
> ```

> [accordion] Convert a field's type
>
> `output` converts the value picked by `path`. Here the price comes back as text.
>
> ```bash theme={null}
> ?idx=0&path=price&output=text
> ```
>
> ```json Response theme={null}
> "12.5"
> ```

> [accordion] Products under a price
>
> Search with `op=lt` (less than). `gt` and `lt` compare as numbers.
>
> ```bash theme={null}
> ?q=price&value=20&op=lt
> ```
>
> ```json Response theme={null}
> [
>   { "id": 1, "name": "Classic Mug", "category": "kitchen", "price": 12.5, "tags": [{ "label": "ceramic" }, { "label": "gift" }] },
>   { "id": 2, "name": "Canvas Tote", "category": "bags", "price": 18, "tags": [{ "label": "cotton" }] }
> ]
> ```

> [accordion] Name contains a word
>
> `il` matches a pattern, ignoring case. `%` is the wildcard and must be sent as `%25` in a URL.
>
> ```bash theme={null}
> ?q=name&value=%25mug%25&op=il
> ```
>
> ```json Response theme={null}
> [
>   { "id": 1, "name": "Classic Mug", "category": "kitchen", "price": 12.5, "tags": [{ "label": "ceramic" }, { "label": "gift" }] },
>   { "id": 3, "name": "Travel Mug", "category": "kitchen", "price": 24, "tags": [{ "label": "steel" }, { "label": "gift" }] }
> ]
> ```

> [accordion] Products with a tag
>
> A double dot (`..`) looks inside an array on each product. A product matches when any of its tags matches.
>
> ```bash theme={null}
> ?q=tags..label&value=gift&op=eq
> ```
>
> ```json Response theme={null}
> [
>   { "id": 1, "name": "Classic Mug", "category": "kitchen", "price": 12.5, "tags": [{ "label": "ceramic" }, { "label": "gift" }] },
>   { "id": 3, "name": "Travel Mug", "category": "kitchen", "price": 24, "tags": [{ "label": "steel" }, { "label": "gift" }] }
> ]
> ```

> [accordion] Combine two conditions
>
> Repeat `q`, `value`, and `op` for each condition. All of them must match.
>
> ```bash theme={null}
> ?q=category&value=kitchen&op=eq&q=price&value=20&op=gt
> ```
>
> Only one product matches, so it comes back on its own, not in an array:
>
> ```json Response theme={null}
> { "id": 3, "name": "Travel Mug", "category": "kitchen", "price": 24, "tags": [{ "label": "steel" }, { "label": "gift" }] }
> ```

> [accordion] Just the names of matching products
>
> Add `path` to a search to pick one field from each match.
>
> ```bash theme={null}
> ?q=price&value=20&op=gt&path=name
> ```
>
> ```json Response theme={null}
> ["Travel Mug", "Leather Backpack"]
> ```

## A small client

Search returns an array for two or more matches, a single object for one match, and `404` for none. This helper smooths that out, so your code always gets an array.

```javascript catalog.js theme={null}
const SILO_URL = process.env.JSONSILO_URL; // https://[region-code].jsonsilo.com/[file-uuid]
const ACCESS_KEY = process.env.JSONSILO_ACCESS_KEY;

/**
 * conditions: [{ field: 'price', op: 'lt', value: 20 }, ...]
 */
export async function searchProducts(conditions, { path } = {}) {
  const url = new URL(SILO_URL);
  for (const { field, op = 'eq', value } of conditions) {
    url.searchParams.append('q', field);
    url.searchParams.append('value', String(value)); // % is encoded as %25 for you
    url.searchParams.append('op', op);
  }
  if (path) url.searchParams.set('path', path);

  const res = await fetch(url, { headers: { 'X-SILO-KEY': ACCESS_KEY } });
  if (res.status === 404) return [];
  if (!res.ok) throw new Error(`JSONsilo returned ${res.status}`);

  const data = await res.json();
  return Array.isArray(data) ? data : [data];
}

// Usage
const cheap = await searchProducts([{ field: 'price', op: 'lt', value: 20 }]);
const mugs = await searchProducts([{ field: 'name', op: 'il', value: '%mug%' }]);
const giftNames = await searchProducts(
  [{ field: 'tags..label', value: 'gift' }],
  { path: 'name' }
);
```

```python catalog.py theme={null}
import os

import requests

SILO_URL = os.environ["JSONSILO_URL"]  # https://[region-code].jsonsilo.com/[file-uuid]
ACCESS_KEY = os.environ["JSONSILO_ACCESS_KEY"]


def search_products(conditions, path=None):
    """conditions: [("price", "lt", 20), ...]"""
    params = []
    for field, op, value in conditions:
        params += [("q", field), ("value", str(value)), ("op", op)]
    if path:
        params.append(("path", path))

    res = requests.get(
        SILO_URL, params=params, headers={"X-SILO-KEY": ACCESS_KEY}, timeout=5
    )
    if res.status_code == 404:
        return []
    res.raise_for_status()

    data = res.json()
    return data if isinstance(data, list) else [data]


# Usage
cheap = search_products([("price", "lt", 20)])
mugs = search_products([("name", "il", "%mug%")])
gift_names = search_products([("tags..label", "eq", "gift")], path="name")
```

> [!NOTE]
>
> A `404` can also mean a wrong UUID or region. If every search returns nothing, read the silo without parameters first to check the URL.

## Good to know

* **Results are cached for up to 5 minutes.** A search right after you update the catalog may return the previous data.
* **Every query is a read.** Queries and searches count towards the silo's [rate limit](https://docs.jsonsilo.com/rate-limits.md) like any other private silo read.
* **No sorting or paging.** Sort and slice the results in your own code.
* **Private silos only.** A public silo always returns the whole document.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.