# Utilizando os filtros no Skyone Studio

Para realizar consultas avançadas na API do **Skyone Studio**, utilize o parâmetro de *query*. O valor deste parâmetro deve ser um objeto JSON válido enviado no padrão *underline query*.

### Estrutura Base do JSON

Abaixo, a estrutura completa que engloba ordenação, filtragem por período e paginação:

```json
{
  "sort": {
    "startTimeUTC": -1
  },
  "filter": {
    "startTimeUTC": {
      "_period_greater_equal": "2026-01-01T00:00:00Z",
      "_period_smaller_equal": "2026-01-06T23:59:59Z"
    }
  },
  "pagination": {
    "limit": 10,
    "skip": 0
  }
}
```

Abaixo, compreenda melhor os itens: 

### Paginação (Pagination)

Controla a quantidade de dados retornados por requisição para otimizar a performance.

* **limit:** Define o número máximo de itens por página.
* **skip:** Define quantos itens devem ser pulados (offset) para acessar as próximas páginas

Exemplo:

```json
"pagination": {
  "limit":10
  "skip": 0
}

```

### Filtro (Filter)

O objeto *filter* permite refinar sua busca utilizando chaves específicas e operadores de comparação.

<table data-header-hidden><thead><tr><th width="145.78515625"></th><th width="193.35546875"></th><th></th></tr></thead><tbody><tr><td><strong>Operador</strong></td><td><strong>Descrição</strong></td><td><strong>Exemplo de Uso</strong></td></tr><tr><td><code>_equal</code></td><td>Filtra os registros cujo valor da coluna corresponde exatamente ao valor especificado, respeitando caracteres e diferenciação entre maiúsculas e minúsculas.</td><td><code>"status": {"_equal": "active"}</code></td></tr><tr><td><code>_diff</code></td><td>Filtra os registros cujo valor da coluna não corresponde ao valor especificado.</td><td><code>"id": {"_diff": 0}</code></td></tr><tr><td><code>_like</code></td><td>Filtra os registros nos quais o valor da coluna contém o termo pesquisado, permitindo buscas parciais.</td><td><code>"name": {"_like": "Sky"}</code></td></tr><tr><td><code>_greater</code></td><td>Filtra os registros cujo valor da coluna é maior que o valor especificado.</td><td><code>"price": {"_greater": 50}</code></td></tr><tr><td><code>_smaller</code></td><td>Filtra os registros cujo valor é menor que o valor limite especificado.</td><td><code>"stock": {"_smaller": 10}</code></td></tr><tr><td><code>_greater_equal</code></td><td>Filtra os registros cujo valor é maior ou igual ao valor limite especificado.</td><td><code>"age": {"_greater_equal": 18}</code></td></tr><tr><td><code>_smaller_equal</code></td><td>Filtra os registros cujo valor é menor ou igual ao valor limite especificado.</td><td><code>"limit": {"_smaller_equal": 100}</code></td></tr><tr><td><code>_exists</code></td><td>Filtra os registros com base na existência do campo/coluna no documento, retornando aqueles em que o campo está presente (<code>true</code>) ou ausente (<code>false</code>), independentemente do seu valor.</td><td><code>"tag": {"_exists": true}</code></td></tr><tr><td><code>_not_exists</code></td><td>Filtra os registros em que o campo/coluna não existe no documento, independentemente de valor.</td><td><code>"deletedAt": {"_not_exists": true}</code></td></tr><tr><td><code>_in</code></td><td>Filtra os registros cujo valor da coluna está contido em uma lista (array) de valores fornecidos.</td><td><code>"role": {"_in": ["admin", "editor"]}</code></td></tr></tbody></table>

#### Filtros de Período (Data/Hora)

Para campos de data como ***startTimeUTC***, utilize os prefixos de período:

* **\_period\_greater:** Data posterior a.
* **\_period\_smaller:** Data anterior a.
* **\_period\_greater\_equal:** Data inicial (inclusive).
* **\_period\_smaller\_equal:** Data final (inclusive).

No cenário abaixo, o filtro atua como && (and):

```json
"startTimeUTC": {
      "_period_greater_equal": "2026-01-01T00:00:00Z",
      "_period_smaller_equal": "2026-01-06T23:59:59Z"
    }
```

### Ordenação (Sort)

Define a direção em que os resultados são retornados com base em uma chave, sendo que:

* -1: Ordem Decrescente (padrão).
* 1: Ordem Crescente.

\
Exemplo:

```json
{
  "sort":{
    "startTimeUTC":-1
  }
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.skyone.cloud/skyone-studio/how-to/utilizando-os-filtros-no-skyone-studio.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.