> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentação da cláusula LIMIT

# LIMIT

A cláusula `LIMIT` controla quantas linhas são retornadas no resultado da sua consulta. As linhas podem ser selecionadas por contagem e offset, ou pelas condições que abrem e fecham um intervalo de linhas com [`LIMIT ... AFTER ... UNTIL`](#limit-after-until).

## Sintaxe básica

**Selecione as primeiras linhas:**

```sql theme={null}
LIMIT m
```

Retorna as primeiras `m` linhas do resultado, ou todos os registros se houver menos de `m`.

**Sintaxe alternativa de TOP (compatível com o MS SQL Server):**

```sql theme={null}
-- SELECT TOP number|percent column_name(s) FROM table_name
SELECT TOP 10 * FROM numbers(100);
SELECT TOP 0.1 * FROM numbers(100);
```

Isso equivale a `LIMIT m` e pode ser usado por compatibilidade com consultas do Microsoft SQL Server.

**SELECT com OFFSET:**

```sql theme={null}
LIMIT m OFFSET n
-- or equivalently:
LIMIT n, m
```

Ignora as primeiras `n` linhas e retorna as próximas `m` linhas.

Em ambas as formas, `n` e `m` devem ser inteiros não negativos.

**Selecione um intervalo por condições:**

```sql theme={null}
LIMIT [n] AFTER start_expr [UNTIL end_expr]
LIMIT [n] UNTIL end_expr
```

Retorna as linhas a partir da primeira linha em que `start_expr` é true, ou desde o início do stream quando `AFTER` é omitido, até a primeira linha em ou após esse início em que `end_expr` é true, sem incluí-la; `n` limita o tamanho desse range. `AFTER start_expr ALL` abre um range em cada linha correspondente. Veja [LIMIT ... AFTER ... UNTIL](#limit-after-until) abaixo.

## Limites negativos

Selecione linhas do *fim* do conjunto de resultados usando valores negativos:

| Sintaxe | Resultado |
| - | - |
| `LIMIT -m` | Últimas `m` linhas |
| `LIMIT -m OFFSET -n` | Últimas `m` linhas após ignorar as últimas `n` linhas |
| `LIMIT m OFFSET -n` | Primeiras `m` linhas após ignorar as últimas `n` linhas |
| `LIMIT -m OFFSET n` | Últimas `m` linhas após ignorar as primeiras `n` linhas |

A sintaxe `LIMIT -n, -m` é equivalente a `LIMIT -m OFFSET -n`.

## Limites fracionários

Use valores decimais entre 0 e 1 para selecionar uma porcentagem das linhas:

| Sintaxe | Resultado |
| - | - |
| `LIMIT 0.1` | Primeiros 10% das linhas |
| `LIMIT 1 OFFSET 0.5` | A linha mediana |
| `LIMIT 0.25 OFFSET 0.5` | Terceiro quartil (25% das linhas após pular os primeiros 50%) |

<Note>
  * As frações devem ser valores [Float64](/pt-BR/reference/data-types/float) maiores que 0 e menores que 1.
  * Contagens fracionárias de linhas são arredondadas para o número inteiro seguinte.
</Note>

## Combinando tipos de LIMIT

Você pode combinar inteiros padrão com offsets fracionários ou negativos:

```sql theme={null}
LIMIT 10 OFFSET 0.5    -- 10 rows starting from the halfway point
LIMIT 10 OFFSET -20    -- 10 rows after skipping the last 20
```

A [forma de intervalo](#limit-after-until) só pode ser combinada com uma contagem simples de linhas: `LIMIT 3 AFTER start_expr` retorna no máximo três linhas a partir do ponto em que o intervalo se abre. `OFFSET`, contagens fracionárias e negativas e `WITH TIES` são rejeitados quando usados junto com `AFTER` ou `UNTIL`. Uma cláusula [`LIMIT BY`](/pt-BR/reference/statements/select/limit-by) pode preceder um intervalo na mesma consulta, e a configuração [`limit`](/pt-BR/reference/settings/session-settings/other#limit) continua limitando o resultado.

## LIMIT ... WITH TIES

O modificador `WITH TIES` inclui linhas adicionais com os mesmos valores de `ORDER BY` da última linha dentro do limite. Ele se aplica apenas a limites de contagem e offset e não pode ser combinado com a [forma de intervalo](#limit-after-until).

```sql theme={null}
SELECT * FROM (
    SELECT number % 50 AS n FROM numbers(100)
) ORDER BY n LIMIT 0, 5
```

```response theme={null}
┌─n─┐
│ 0 │
│ 0 │
│ 1 │
│ 1 │
│ 2 │
└───┘
```

Com `WITH TIES`, todas as linhas com o mesmo último valor são incluídas:

```sql theme={null}
SELECT * FROM (
    SELECT number % 50 AS n FROM numbers(100)
) ORDER BY n LIMIT 0, 5 WITH TIES
```

```response theme={null}
┌─n─┐
│ 0 │
│ 0 │
│ 1 │
│ 1 │
│ 2 │
│ 2 │
└───┘
```

A linha 6 é incluída porque tem o mesmo valor (`2`) da linha 5.

O mesmo acontece quando o offset é especificado com a palavra-chave `OFFSET`:

```sql theme={null}
SELECT * FROM (
    SELECT number % 50 AS n FROM numbers(100)
) ORDER BY n LIMIT 3 OFFSET 2 WITH TIES
```

```response theme={null}
┌─n─┐
│ 1 │
│ 1 │
│ 2 │
│ 2 │
└───┘
```

Pular as 2 primeiras linhas e retornar 3 normalmente resultaria em `1, 1, 2`, mas o segundo `2` é incluído porque tem o mesmo valor da última linha.

`WITH TIES` também funciona com limites e offsets negativos. Ele inclui linhas adicionais com os mesmos valores de `ORDER BY` da primeira linha selecionada:

```sql theme={null}
SELECT number % 3 AS n FROM numbers(15)
ORDER BY n LIMIT -4 OFFSET -3 WITH TIES
```

```response theme={null}
┌─n─┐
│ 1 │
│ 1 │
│ 1 │
│ 1 │
│ 1 │
│ 2 │
│ 2 │
└───┘
```

Sem `WITH TIES`, o resultado seria `1, 1, 2, 2`. Com `WITH TIES`, três linhas extras com valor `1` são incluídas porque têm o mesmo valor da primeira linha selecionada.

Esse modificador pode ser combinado com o modificador [`ORDER BY ... WITH FILL`](/pt-BR/reference/statements/select/order-by#order-by-expr-with-fill-modifier).

## LIMIT ... AFTER ... UNTIL (intervalo por condições)

Você pode limitar o resultado a um *intervalo* de linhas entre duas condições de fronteira:

```sql theme={null}
LIMIT [n] AFTER start_expr [UNTIL end_expr]
LIMIT [n] AFTER start_expr ALL [UNTIL end_expr]
LIMIT [n] UNTIL end_expr
```

* `AFTER start_expr`: Inicia a saída a partir da primeira linha em que `start_expr` é true (essa linha é incluída).
* `AFTER start_expr ALL`: Gera a união de todos os intervalos correspondentes que começam onde `start_expr` é true, sem duplicar linhas quando os intervalos se sobrepõem.
* `UNTIL end_expr`: Encerra cada intervalo antes da primeira linha, no início dele ou após ele, em que `end_expr` é true (essa linha é excluída).
* `n`: Contagem opcional de linhas. Sem `ALL`, é o comprimento máximo do único intervalo aberto. Com `AFTER ... ALL`, é o comprimento de *cada* intervalo aberto, de modo que o resultado total pode exceder `n` (por exemplo, `LIMIT 2 AFTER number IN (2, 6) ALL` pode retornar até quatro linhas). Para limitar o número total de linhas do resultado, use o SETTING `limit`, que é aplicado como um limite global após o intervalo.

A ordem do stream (a ordem em que as linhas são lidas) define qual é a "primeira" correspondência; use `ORDER BY` para controlá-la.

Correspondências de `UNTIL` anteriores ao início de um intervalo não têm efeito. Se ambas as condições corresponderem à linha inicial, o intervalo fica vazio. Se nenhuma correspondência de `UNTIL` ocorrer no início ou após ele, o intervalo continua até atingir sua contagem de linhas `n` ou o fim do stream. Com `AFTER ... ALL`, correspondências posteriores de `AFTER` podem abrir novos intervalos depois que um intervalo anterior é encerrado.

Com `AFTER` e sem `ALL`, o passo de intervalo avalia `AFTER` até encontrar um fragmento que contenha uma correspondência inicial. Em seguida, avalia `UNTIL` nesse fragmento e nos fragmentos subsequentes enquanto o intervalo permanecer aberto. As expressões são avaliadas sobre fragmentos inteiros, portanto `UNTIL` ainda pode ser avaliado para linhas anteriores ao início dentro do fragmento inicial.

Se `UNTIL` contiver funções stateful como `rowNumberInAllBlocks`, ou funções que sejam não determinísticas dentro da consulta, ele é avaliado a partir do primeiro fragmento para preservar o comportamento dessas funções. Sem `ALL`, `AFTER` é avaliado apenas até o fragmento inicial; os fragmentos subsequentes avaliam somente `UNTIL`. Correspondências de fim anteriores ao início continuam sem efeito.

**Exemplos:**

Primeiras 3 linhas a partir da primeira linha em que `number >= 3`:

```sql theme={null}
SELECT number FROM numbers(10) ORDER BY number LIMIT 3 AFTER number >= 3;
```

```response theme={null}
┌─number─┐
│      3 │
│      4 │
│      5 │
└────────┘
```

Linhas a partir da primeira linha em que `number >= 2` até (exclusive) a primeira linha em que `number >= 6`:

```sql theme={null}
SELECT number FROM numbers(10) ORDER BY number LIMIT 10 AFTER number >= 2 UNTIL number >= 6;
```

```response theme={null}
┌─number─┐
│      2 │
│      3 │
│      4 │
│      5 │
└────────┘
```

Sem `n`, são retornadas todas as linhas desde a correspondência de `AFTER` até o fim do stream (ou até `UNTIL`):

```sql theme={null}
SELECT number FROM numbers(10) ORDER BY number LIMIT AFTER number >= 7;
```

```response theme={null}
┌─number─┐
│      7 │
│      8 │
│      9 │
└────────┘
```

Sem `n`, mas com `UNTIL`, o intervalo vai da primeira correspondência de `AFTER` até a primeira correspondência de `UNTIL` nela ou após ela:

```sql theme={null}
SELECT number FROM numbers(10) ORDER BY number LIMIT AFTER number >= 2 UNTIL number >= 6;
```

```response theme={null}
┌─number─┐
│      2 │
│      3 │
│      4 │
│      5 │
└────────┘
```

Uma correspondência de `UNTIL` anterior ao início é ignorada; aqui, `number = 1` não tem efeito, e o intervalo termina antes de `number = 6`:

```sql theme={null}
SELECT number FROM numbers(10) ORDER BY number LIMIT AFTER number = 3 UNTIL number IN (1, 6);
```

```response theme={null}
┌─number─┐
│      3 │
│      4 │
│      5 │
└────────┘
```

Emitir 2 linhas após cada linha correspondente, sem duplicar sobreposições:

```sql theme={null}
SELECT number FROM numbers(10) ORDER BY number LIMIT 2 AFTER number IN (2, 3, 6) ALL;
```

```response theme={null}
┌─number─┐
│      2 │
│      3 │
│      4 │
│      6 │
│      7 │
└────────┘
```

Com `ALL` e `UNTIL`, todo intervalo aberto termina após `n` linhas ou na próxima correspondência de `UNTIL`, o que ocorrer primeiro; aqui o intervalo aberto em 6 é interrompido por `number = 7`:

```sql theme={null}
SELECT number FROM numbers(10) ORDER BY number LIMIT 2 AFTER number IN (2, 6) ALL UNTIL number = 7;
```

```response theme={null}
┌─number─┐
│      2 │
│      3 │
│      6 │
└────────┘
```

Sem `n`, uma correspondência de `UNTIL` fecha o intervalo atual e uma correspondência posterior de `AFTER` abre um novo, que se estende até o fim quando nenhuma outra correspondência de `UNTIL` ocorre:

```sql theme={null}
SELECT number FROM numbers(10) ORDER BY number LIMIT AFTER number IN (2, 6) ALL UNTIL number = 4;
```

```response theme={null}
┌─number─┐
│      2 │
│      3 │
│      6 │
│      7 │
│      8 │
│      9 │
└────────┘
```

Sem `n` e sem `UNTIL`, todo intervalo aberto se estende até o fim do stream, portanto `AFTER start_expr ALL` retorna as mesmas linhas que `AFTER start_expr`.

<Note>
  * `WITH TIES`, `LIMIT`/`OFFSET` fracionários/negativos e `OFFSET` não são suportados em conjunto com `AFTER`/`UNTIL`.
  * O pushdown preliminar de `LIMIT` é desabilitado quando `AFTER`/`UNTIL` é usado.
  * `AFTER` e `UNTIL` são reconhecidos como palavras-chave apenas quando são seguidos por uma expressão de fronteira, de modo que um identificador chamado `after` ou `until` continua funcionando como contagem de linhas (`LIMIT after`, `LIMIT after BY x`). Quando as duas leituras são possíveis, a palavra-chave prevalece: `LIMIT after(2)` é o intervalo `LIMIT AFTER (2)`; escreva `LIMIT (after(2))` para chamar uma função chamada `after`.
</Note>

`UNTIL` sozinho retorna as linhas desde o início do stream até a primeira linha em que a condição é true:

```sql theme={null}
SELECT number FROM numbers(10) ORDER BY number LIMIT UNTIL number >= 3;
```

```response theme={null}
┌─number─┐
│      0 │
│      1 │
│      2 │
└────────┘
```

Com `n`, `UNTIL` sozinho retorna no máximo `n` linhas a partir do início do stream, parando ainda na primeira correspondência:

```sql theme={null}
SELECT number FROM numbers(10) ORDER BY number LIMIT 2 UNTIL number >= 3;
```

```response theme={null}
┌─number─┐
│      0 │
│      1 │
└────────┘
```

Um intervalo pode vir depois de [`LIMIT BY`](/pt-BR/reference/statements/select/limit-by), aplicando-se então às linhas mantidas pelo `LIMIT BY`:

```sql theme={null}
SELECT number % 4 AS k, number FROM numbers(12) ORDER BY k, number LIMIT 2 BY k LIMIT 3 AFTER k >= 1;
```

```response theme={null}
┌─k─┬─number─┐
│ 1 │      1 │
│ 1 │      5 │
│ 2 │      2 │
└───┴────────┘
```

## Considerações

**Resultados não determinísticos:** Sem a cláusula [`ORDER BY`](/pt-BR/reference/statements/select/order-by), as linhas retornadas podem ser arbitrárias e variar entre execuções da consulta.

**Limite no servidor:** O número de linhas retornadas também pode ser afetado pela configuração [limit](/pt-BR/reference/settings/session-settings/other#limit).

## Veja também

* [LIMIT BY](/pt-BR/reference/statements/select/limit-by) — Limita o número de linhas por grupo de valores, útil para obter os N principais resultados em cada categoria.