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

# Compute sob demanda do ClickHouse

> Adicione compute para workloads do ClickHouse Cloud sem redimensionar seu primary service. O suporte em private preview é limitado a consultas selecionadas.

export const Image = ({img, alt, size = "lg", background}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  const backgroundColor = background === "white" ? "white" : background === "black" ? "rgb(31 31 28)" : undefined;
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} style={{
    backgroundColor
  }} />
      </Frame>
    </div>;
};

export const PrivatePreviewBadge = () => {
  return <div className="privatePreviewBadge">
            <div className="privatePreviewIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path d="M5.33301 6.66667V4.66667V4.66667C5.33301 3.194 6.52701 2 7.99967 2V2C9.47234 2 10.6663 3.194 10.6663 4.66667V4.66667V6.66667" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path d="M8.00033 9.33337V11.3334" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path fillRule="evenodd" clipRule="evenodd" d="M11.333 14H4.66634C3.92967 14 3.33301 13.4033 3.33301 12.6666V7.99996C3.33301 7.26329 3.92967 6.66663 4.66634 6.66663H11.333C12.0697 6.66663 12.6663 7.26329 12.6663 7.99996V12.6666C12.6663 13.4033 12.0697 14 11.333 14Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            {'Em prévia privada'}
        </div>;
};

<PrivatePreviewBadge />

<Note>
  O On-Demand Compute está em private preview. Ele não é coberto pelos SLOs ou SLAs do ClickHouse Cloud e podem se aplicar limitações conhecidas e desconhecidas. Consulte [Limitações](#limitations).

  [Entre na lista de espera](https://clickhouse.com/cloud/on-demand-compute-waitlist).
</Note>

O On-Demand Compute é uma capability do ClickHouse Cloud que oferece ao seu cloud service (um tenant) capacidade adicional e instantânea para workloads compatíveis, sem exigir que você redimensione ou provisione outro service. Esse trabalho é executado em workers do ClickHouse, fora do processamento do próprio service. Os workers vêm de um pool gerenciado compartilhado entre tenants na mesma região, mas cada worker é atribuído a apenas um tenant por vez.

Durante o private preview, o On-Demand Compute oferece suporte apenas a consultas `SELECT`. Você habilita uma consulta por meio de settings em nível de consulta/session/USER, e o ClickHouse atribui workers do pool para executá-la por meio do seu service e endpoint existentes.

Isso é diferente da [separação de processamento](/pt-BR/products/cloud/features/infrastructure/warehouses). Um warehouse oferece processamento dedicado e de longa duração por meio de múltiplos services que compartilham dados. O On-Demand Compute oferece workers temporários de um pool compartilhado, por meio do seu service existente.

O On-Demand Compute utiliza capabilities totalmente novas:

* Execução de consulta sem estado com On-Demand Compute
* Um novo [CBO](https://github.com/ClickHouse/ClickHouse/pull/86353) (cost-based optimizer)
* Uma nova [execução de consulta distribuída](https://clickhouse.com/blog/multi-stage-distributed-query-execution-clickhouse-cloud)

<h2 id="when-to-use-on-demand-compute">
  Quando usar o On-Demand Compute
</h2>

Durante o private preview, use o On-Demand Compute para consultas `SELECT` elegíveis e de uso intensivo de computação que você queira executar fora do compute do primary service:

* **Consultas ad hoc e analíticas:** execute consultas `SELECT` de uso intensivo de computação em workers adicionais.
* **Workloads de leitura não críticas:** tire leituras selecionadas do primary service.
* **Consultas em lago de dados:** consulte dados compatíveis do Apache Iceberg, Delta Lake ou `SharedMergeTree` em workers adicionais.
* **Compute adicional temporário:** solicite workers para consultas elegíveis sem redimensionar o primary service.

O private preview oferece suporte apenas a consultas `SELECT`. Os workers não executam consultas `INSERT`, DDL, mutações nem background operations.

<h2 id="how-it-works">
  Como funciona
</h2>

1. Você envia uma consulta `SELECT` elegível ao seu ClickHouse Cloud service solicitando um número específico de workers. Seu endpoint, sua authentication e sua configuração de RBAC permanecem inalterados
2. Seu cluster então se conecta ao pool e solicita o número especificado de workers
3. Os workers são leased por uma duração de pelo menos 60 segundos; se a consulta durar mais, o lease é renovado automaticamente
4. Os workers recebem a consulta e a executam
5. A resposta é então enviada de volta ao seu client
6. Os workers são apagados.

Durante o private preview, cada worker tem `8 vCPUs` e `32 GiB` de memória. Use `distributed_plan_workers_num` para especificar quantos workers a consulta solicita.

<h2 id="using-on-demand-compute">
  Usando compute sob demanda
</h2>

<h3 id="settings">
  Settings
</h3>

Use estas configurações para começar a usar o on-demand compute:

| Setting | Valor obrigatório | Finalidade |
| - | - | - |
| `make_distributed_plan` | Sim | Habilita o plano de consulta distribuído experimental. Obrigatório para o On-Demand Compute. |
| `distributed_plan_workers_num` | Sim | Número de workers a serem alocados para esta consulta. Se for `0` (o padrão), a consulta é executada no seu service, e não no pool de workers. |
| `enable_parallel_replicas` | Sim (defina como `0`) | Parallel replicas são incompatíveis com o distributed plan. |
| `distributed_plan_fallback_to_local_execution` | Não (padrão `0`) | Configuração para recorrer à execução local quando um plano não puder ser distribuído (só tem efeito com `make_distributed_plan`) |

<Tip>
  Durante o preview, defina as configurações no nível da consulta ou crie um usuário separado com configurações diferentes. Assim fica evidente quais instruções usam o On-Demand Compute.
</Tip>

<h3 id="example">
  Exemplo
</h3>

Algumas consultas não podem ser distribuídas entre os workers:

```sql theme={null}
SELECT count()
FROM nyctaxi.trips
SETTINGS distributed_plan_fallback_to_local_execution = 0, make_distributed_plan = 1, distributed_plan_workers_num = 5

Query id: c1c96ede-0c4c-414f-b103-f27f0b7d34c7


Elapsed: 0.992 sec.

Received exception from server (version 26.9.1):
Code: 344. DB::Exception: Received from nuqae0jhz5.eu-west-1.aws.clickhouse-staging.com:9440. DB::Exception: make_distributed_plan cannot distribute this query: it contains the step ReadFromPreparedSource which could not execute remotely. (SUPPORT_IS_DISABLED)
```

Para garantir que as consultas recorram à execução local como fallback, use a configuração `distributed_plan_fallback_to_local_execution`:

```sql theme={null}
SELECT count()
FROM nyctaxi.trips
SETTINGS distributed_plan_fallback_to_local_execution = 1, make_distributed_plan = 1, distributed_plan_workers_num = 5

Query id: c7b09855-e3c3-40ef-9790-5374e0726f26

   ┌─count()─┐
1. │   21932 │
   └─────────┘

1 row in set. Elapsed: 0.896 sec.
```

```sql theme={null}
SELECT
    sum(l_extendedprice * l_discount) AS revenue
FROM lineitem
WHERE
    l_shipdate >= DATE '1994-01-01'
    AND l_shipdate < DATE '1994-01-01' + INTERVAL 1 YEAR
    AND l_discount BETWEEN 0.06 - 0.01 AND 0.06 + 0.01
    AND l_quantity < 24
SETTINGS
    make_distributed_plan = 1,
    distributed_plan_workers_num = 5,
    enable_parallel_replicas = 0
```

Essa consulta solicita cinco workers. O número de workers que o ClickHouse disponibiliza depende do limite do private preview e da capacidade disponível do pool.

<h3 id="concurrent-queries">
  Consultas concorrentes
</h3>

Consultas concorrentes do mesmo ClickHouse Cloud service podem compartilhar os workers atribuídos. O ClickHouse solicita workers adicionais somente quando uma consulta requer mais workers do que os já atribuídos ao service.

Por exemplo, se duas consultas concorrentes solicitarem três workers cada, elas podem compartilhar os mesmos três workers. Se outra consulta solicitar cinco workers, o ClickHouse pode usar os três workers atribuídos e solicitar mais dois do pool.

Veja o exemplo abaixo:

```sql theme={null}
SELECT ... SETTINGS make_distributed_plan = 1, distributed_plan_workers_num = 3, ...;
SELECT ... SETTINGS make_distributed_plan = 1, distributed_plan_workers_num = 3, ...;
```

Elas compartilham os mesmos três workers.

Se uma terceira consulta concorrente solicitar cinco workers:

```sql theme={null}
SELECT ... SETTINGS make_distributed_plan = 1, distributed_plan_workers_num = 5, ...;
```

Essa consulta é executada nos três workers existentes, além de dois workers recém-obtidos por lease.

<h3 id="pool-capacity">
  Quando o pool não consegue atender à requisição
</h3>

A disponibilidade de workers é de melhor esforço durante o private preview. Se houver menos workers disponíveis do que o solicitado, a consulta é executada com os workers que o ClickHouse conseguir atribuir. Por exemplo, uma requisição de cinco workers pode ser executada com três.

Se nenhum worker puder ser alocado, a consulta falha.

Tente executar a consulta novamente. Se o problema persistir, entre em contato com a equipe de conta da ClickHouse — o pool de preview pode estar esgotado ou dimensionado incorretamente.

<h2 id="monitoring">
  Monitoring
</h2>

Use a `system.query_log` no seu service para saber quantos workers foram alocados à sua consulta.

<h3 id="worker-provided">
  Número de workers alocados
</h3>

```sql theme={null}
SELECT
    ProfileEvents['StatelessWorkerRequested'],
    ProfileEvents['StatelessWorkerProvided']
FROM clusterAllReplicas(default, system.query_log)
WHERE query_id = '<YOUR_QUERY_ID>'
  AND type != 'QueryStart';
```

<Tip>
  Defina `log_comment = 'on-demand'` (ou um nome de workload) nas consultas On-Demand para poder filtrá-las sem precisar fazer o parsing de `Settings`.
</Tip>

```sql theme={null}
SELECT
    sum(l_extendedprice * l_discount) AS revenue
FROM lineitem
WHERE
    l_shipdate >= DATE '1994-01-01'
    AND l_shipdate < DATE '1994-01-01' + INTERVAL 1 YEAR
    AND l_discount BETWEEN 0.06 - 0.01 AND 0.06 + 0.01
    AND l_quantity < 24
SETTINGS
    make_distributed_plan = 1,
    distributed_plan_workers_num = 5,
    enable_parallel_replicas = 0,
    log_comment = 'on-demand-private-preview'
```

<h2 id="available-regions">
  Regiões disponíveis
</h2>

O On-Demand Compute é regional: os workers são executados na mesma região do seu serviço.

| Cloud | Região | Notas |
| - | - | - |
| AWS | us-east-1 | |
| AWS | eu-west-1 | |

Se a sua região não estiver na lista, solicite-a na [lista de espera](https://clickhouse.com/cloud/on-demand-compute-waitlist). Habilitaremos mais regiões conforme a demanda.

<h2 id="pricing">
  Preço
</h2>

Durante o private preview, o compute sob demanda é gratuito, sujeito a um limite de uso (consulte [Limitações](#limitations)). Fale com a account team da ClickHouse caso precise que esse limite seja aumentado.

O preço será definido quando o preview terminar. Os participantes do preview serão notificados antes de o recurso ser promovido para beta e antes do início de qualquer cobrança.

O modelo previsto é o mesmo do compute do ClickHouse Cloud: você paga pelo compute que utiliza (tempo de worker alocado), e não por dados varridos ou linhas lidas.

<h2 id="limitations">
  Limitações
</h2>

As limitações a seguir se aplicam durante o private preview. Outras limitações podem se aplicar. Relate comportamentos inesperados ao suporte do ClickHouse ou à sua account team.

* **Apenas consultas `SELECT`.** Os workers não executam consultas `INSERT`, mutações, DDL nem background operations.
* **Formato com suporte.** O private preview oferece suporte a Apache Iceberg, Delta Lake e `SharedMergeTree`.
* **Parallel replicas.** As parallel replicas devem estar desabilitadas.
* **Tamanho do worker.** Cada worker tem `8 vCPUs` e `32 GiB` de memória.
* **Limite de workers.** Cada consulta pode solicitar até cinco workers durante o private preview.
* **Capacidade do pool.** A disponibilidade de workers é de melhor esforço. Uma consulta pode receber menos workers do que solicitou. Se nenhum worker estiver disponível, a consulta falha.
* **Desempenho.** O desempenho varia conforme a consulta. A atribuição de workers, o planejamento distribuído e a transferência dos estágios do plano podem adicionar latência. Alguns formatos de consulta podem apresentar desempenho inferior ao da execução no primary service (suas consultas típicas de menos de um segundo provavelmente terão desempenho melhor no seu cluster)
* **Compatibilidade de consultas.** O distributed planner não consegue executar remotamente todos os planos de consulta. Consultas sem suporte podem retornar uma exceção `SUPPORT_IS_DISABLED`.

<h2 id="roadmap">
  Roadmap
</h2>

O On-Demand Compute é apenas o começo. Trabalhos em andamento ou planejados:

* Eliminar limitações conhecidas (lacunas de `SUPPORT_IS_DISABLED`)
* Pools com workers de tamanhos diferentes
* Estabilizar o desempenho de consultas em comparação com a execução stateful
* Suporte a background merge
* Precificação
* Calibração do escalonador automático do pool de workers
* Observabilidade integrada
* Permissões dedicadas para o On-Demand Compute
* Expansão de workloads de Data Lake (escrita, compaction, etc...)

<h2 id="security">
  Segurança
</h2>

Os workers vêm de um pool pré-aquecido compartilhado entre services na mesma region, por isso existe uma regra inegociável: um worker atende a um service por vez e nunca é repassado de um service para outro.

Nada muda na forma como você acessa o ClickHouse. Os clientes continuam se conectando ao endpoint do seu service com a authentication existente, e apenas o seu service se comunica com os workers em seu nome. Os workers não expõem nenhum endpoint ao cliente.

* **Um service por worker:** um worker é alocado (lease) a um único service durante toda a duração desse lease. Ele nunca é compartilhado por dois services ao mesmo tempo.
* **Sem reutilização entre services:** quando o lease termina, o worker é destruído e substituído por um novo. Um worker nunca é reatribuído a outro service.
* **Sem dados persistentes:** os workers não mantêm armazenamento persistente e não sobrevivem ao término de um lease.
* **Mesma region do seu service:** os workers são executados na mesma region do service que os aloca, seguindo regras rígidas de residência de dados.
* **Seus access controls existentes continuam valendo:** IP access lists e private endpoints regem o endpoint do seu service exatamente como antes. O On-Demand Compute não adiciona nenhum endpoint para você configurar ou proteger.
* **Sua authentication e RBAC existentes:** as consultas são executadas com o mesmo USER e os mesmos privileges de qualquer outra consulta no seu service. Os workers não possuem identity nem modelo de permission próprios.

<h3 id="network-isolation">
  Isolamento de rede
</h3>

Enquanto um worker está em lease para o seu service, a plataforma permite o tráfego de rede entre esse worker e o seu service e bloqueia todo o restante. A restrição é aplicada na camada de rede, e não no engine de consulta, portanto não depende da consulta, de suas configurações nem do plan produzido pelo optimizer.

<Image img="https://mintcdn.com/private-7c7dfe99-vortex-format/jweE-7zQAicgbBgU/images/cloud/reference/on-demand-compute-worker-isolation.svg?fit=max&auto=format&n=jweE-7zQAicgbBgU&q=85&s=eca0a3627e094e5cb7bb2bb1609d2174" size="lg" alt="Diagrama explicativo do isolamento de rede" width="1320" height="740" data-path="images/cloud/reference/on-demand-compute-worker-isolation.svg" />

* **Somente o seu service consegue alcançar os seus workers.** O path existe durante o lease atual do worker e apenas para aquele service.
* **Workers não atribuídos são inalcançáveis.** Um worker aguardando no pool não tem nenhum path de rede de ou para qualquer service até entrar em lease.
* **Workers em lease para services diferentes não conseguem se alcançar.** Os workers de um mesmo lease trocam entre si estágios do plano e resultados intermediários. Workers de leases diferentes permanecem isolados uns dos outros, mesmo compartilhando um pool.
* **O path é removido junto com o worker.** Encerrar um lease destrói o worker, o que elimina a única coisa que o tráfego tinha permissão para alcançar.
* **O path de request permanece restrito.** Seu service acessa o serviço de assignment de workers para fazer lease e renovar workers. Esse path não transporta dados de consulta e se limita à API de assignment.

<h3 id="authentication-and-authorization">
  Authentication e autorização internas
</h3>

O isolamento de rede determina o que pode alcançar um worker. A authentication determina o que um caller tem permissão de fazer depois de chegar lá, e as duas são aplicadas de forma independente: um caller precisa atender às duas.

Toda connection entre o seu service, o serviço de atribuição de workers e os workers é autenticada. Nada é considerado confiável: todas as credentials são emitidas pela plataforma e distribuídas por lease.

* **Uma credential por worker:** quando workers são cedidos em lease ao seu service, a plataforma emite um token assinado único para cada um deles. Cada token funciona apenas para aquele worker específico e apenas para o seu service.
* **De curta duração e vinculados ao lease:** os tokens expiram junto com o lease que os originou. Renovar um lease emite tokens novos e, uma vez encerrado o lease, seus tokens deixam de autenticar qualquer coisa.
* **Verificados junto à plataforma:** o worker valida o token que lhe é apresentado no serviço de identity da plataforma, em vez de confiar em qualquer informação fornecida na request.

| Connection | O que é autenticado |
| - | - |
| Seu service → serviço de atribuição de workers | A identity de plataforma do seu service, que determina os leases sobre os quais ele pode atuar. |
| Seu service → um worker cedido em lease a ele | Um token assinado restrito àquele único worker, durante a vigência do lease. |
| Worker → worker dentro de um mesmo lease | A própria identity de plataforma de cada worker, além de uma verificação de que o caller ainda mantém um lease ativo sobre o worker de destino. |

<Note>
  Essas credentials são internas ao modo como o ClickHouse Cloud executa a sua consulta. Elas nunca são expostas aos seus clients e não têm relação com a forma como você se autentica no ClickHouse: os clients continuam se conectando com as suas credentials existentes, e os privilégios de consulta continuam sendo regidos pelo RBAC do seu service.
</Note>

<h2 id="faq">
  FAQ
</h2>

<AccordionGroup>
  <Accordion title="O On-Demand Compute é open source?">
    Não. Trata-se de uma arquitetura do ClickHouse Cloud: ClickHouse server (distributed plan), data plane (pool de workers e leases) e control plane. A configuração experimental `make_distributed_plan` e o CBO existem no ClickHouse OSS, mas o pool compartilhado de workers e a execução sem estado são exclusivos do Cloud.
  </Accordion>

  <Accordion title="Preciso de uma versão específica para participar do private preview?">
    Sim. A versão usada durante o private preview será um build personalizado. Podem ser necessários upgrades adicionais ao longo do preview.
  </Accordion>

  <Accordion title="Como será o preço?">
    Ainda não temos um preço público para divulgar. Porém, o uso do recurso é gratuito durante o private preview. Dito isso, a filosofia de preço será a mesma do ClickHouse Cloud: cobrar pelo compute utilizado, e não pelos dados varridos ou pelas linhas lidas. As taxas exatas serão publicadas antes de o preço entrar em vigor.
  </Accordion>

  <Accordion title="Posso usar isso em produção?">
    Você pode executar workloads reais, mas este é um private preview: há limitações conhecidas e desconhecidas, e não existe SLO/SLA para a disponibilidade do pool de workers.
  </Accordion>

  <Accordion title="Qual é a diferença em relação ao autoscaling do meu service?">
    O autoscaling altera o compute atribuído ao seu primary service. Durante o private preview, o On-Demand Compute concede a consultas `SELECT` elegíveis acesso temporário a workers de um pool gerenciado, sem alterar o tamanho do primary service. O autoscaling gerencia a capacidade contínua do service, enquanto o On-Demand Compute fornece compute temporário para workloads específicas.
  </Accordion>

  <Accordion title="Onde posso fazer perguntas?">
    Fale com o seu account team; eles o apresentarão ao product manager do On-Demand Compute.
  </Accordion>

  <Accordion title="Onde posso relatar bugs?">
    Abra um ticket de suporte (severidade 3) ou relate ao product manager. Inclua o `query_id`, o Service ID e a exceção completa.
  </Accordion>

  <Accordion title="Outro ClickHouse Cloud service pode acessar os workers que executam a minha consulta?">
    Não. Enquanto um worker está em lease para o seu service, a plataforma permite tráfego somente entre esse worker e o seu service, bloqueando-o para todos os demais services. Workers não atribuídos e workers em lease para outro service não têm caminho de rede até o seu. Consulte [Isolamento de rede](#network-isolation).
  </Accordion>

  <Accordion title="Um worker é reutilizado por outro service depois que a minha consulta termina?">
    Não. Quando um lease termina, o worker é destruído e substituído por um novo, em vez de ser repassado ao próximo service.
  </Accordion>

  <Accordion title="Isso está disponível no ClickHouse BYOC ou no ClickHouse Private?">
    Não. O private preview não está disponível no ClickHouse BYOC nem no ClickHouse Private.
  </Accordion>
</AccordionGroup>