cogndata/dm-limites-e-melhores-práticas
Habilidade de referência para melhores práticas da API de Modelagem de Dados do CDF. Aborda limites de concorrência (evitando erros 429), padrões de paginação para instances.list e instances.query, operações de escrita em lote, orientação sobre search vs filter e o utilitário QueuedTaskRunner (Semáforo) para controlar requisições concorrentes. Ativadores: DMS limits, 429 error, rate limit, pagination, cursor, nextCursor, batching, semaphore, QueuedTaskRunner, cdfTaskRunner, instances.search, instances.list, instances.query, instances.upsert, concurrency, deadlock.
Introdução
Ao trabalhar com a API de Modelagem de Dados do CDF, é crucial entender os limites de taxa e as melhores práticas para evitar erros como HTTP 429 (Too Many Requests). Esta habilidade fornece orientações sobre como lidar com paginação, escrever operações em lotes e controlar a concorrência usando o QueuedTaskRunner.
Limites de Concorrência e Erros 429
A API DMS impõe limites de taxa para garantir estabilidade. Se muitas requisições forem enviadas simultaneamente, você pode receber um erro 429. Para evitar isso:
- Use semáforos para limitar o número de requisições concorrentes.
- Implemente retry com backoff exponencial para lidar com falhas temporárias.
Padrões de Paginação
instances.list
Ao listar instâncias, use o cursor para paginar pelos resultados:
from cognite.client import CogniteClient
client = CogniteClient()
cursor = None
while True:
response = client.data_modeling.instances.list(
limit=100,
cursor=cursor
)
# Processar instâncias
cursor = response.next_cursor
if not cursor:
break
instances.query
Para consultas, use nextCursor para navegar pelas páginas:
query = "..."
cursor = None
while True:
response = client.data_modeling.instances.query(
query=query,
cursor=cursor
)
# Processar resultados
cursor = response.next_cursor
if not cursor:
break
Operações de Escrita em Lote
Ao atualizar ou criar instâncias, agrupe as operações em lotes para reduzir o número de requisições:
batch = []
for instance in instances:
batch.append(instance)
if len(batch) >= 100:
client.data_modeling.instances.upsert(batch)
batch = []
if batch:
client.data_modeling.instances.upsert(batch)
Search vs Filter
- Search: Use quando precisar de busca textual ou correspondência parcial.
- Filter: Prefira para filtros exatos e eficientes.
QueuedTaskRunner (Semáforo)
O QueuedTaskRunner é um utilitário que ajuda a controlar o número de requisições concorrentes, funcionando como um semáforo:
from cognite.client.data_classes import QueuedTaskRunner
runner = QueuedTaskRunner(max_concurrent=5)
for task in tasks:
runner.submit(task)
runner.wait()
Isso evita sobrecarregar a API e reduz a chance de deadlocks.
Boas Práticas Adicionais
- Monitore os logs para erros 429 e ajuste a concorrência.
- Use o cabeçalho
Retry-Afterquando disponível. - Teste com cargas menores antes de escalar.
Solução de Problemas
Se encontrar erros de concorrência, verifique:
- Se o número de requisições simultâneas está dentro dos limites.
- Se os semáforos estão configurados corretamente.
- Se há dependências circulares nas consultas.