> For the complete documentation index, see [llms.txt](https://docs.skyone.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skyone.cloud/skyone-studio/how-to/utilizando-os-filtros-no-skyone-studio.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.