Azure Cosmos DB vNext Emulator GA: O que muda no desenvolvimento local e em pipelines CI para times brasileiros

O Azure Cosmos DB vNext Emulator foi oficialmente lançado em versão GA. Se você ainda dependia de contas live para testes locais ou pipelines de CI, é hora de reavaliar o fluxo de desenvolvimento.

TL;DR: O Azure Cosmos DB vNext Emulator chegou à versão GA com suporte a Linux, macOS, Windows, x64 e ARM64, além de funcionalidades críticas como vector search, bootstrap via shell scripts, health probes e exportação OpenTelemetry. Para empresas brasileiras, isso significa eliminar dependências de contas live em desenvolvimento, acelerar pipelines CI com datasets determinísticos e viabilizar experimentação local com IA (RAG, buscas semânticas) sem subir custo em nuvem.

A Microsoft anunciou a disponibilidade geral do emulador vNext do Azure Cosmos DB, uma imagem Docker que roda em Linux, macOS e Windows, tanto em x64 quanto ARM64. O objetivo é oferecer uma instância local do Cosmos DB para desenvolvimento e testes, sem necessidade de conta ativa na nuvem. A versão GA traz melhorias significativas desde a preview, incluindo suporte a um shell embarcado, vector search, health probes e integração com OpenTelemetry.

O que muda no dia a dia do desenvolvedor?

O emulador agora pode ser inicializado com dois comandos simples:

Copiardocker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest
docker run -p 8081:8081 -p 8080:8080 -p 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest

Para times de engenharia no Brasil, isso representa a possibilidade de rodar testes de integração localmente sem depender de conectividade com a nuvem — um ganho relevante considerando latências e eventuais instabilidades de rede.

Bootstrap inteligente com Azure Cosmos DB Shell

Um dos destaques é a integração do Azure Cosmos DB Shell — um CLI open-source que permite interagir com o banco via comandos estilo bash. O shell agora vem empacotado na imagem do emulador. Você pode entrar em uma sessão interativa com:

Copiardocker exec -it <container-name> cosmoshell.sh

Mas a funcionalidade mais estratégica é o suporte a scripts de inicialização: qualquer arquivo .csh colocado no diretório /init é executado em ordem alfabética antes do emulador aceitar requisições. Isso elimina a necessidade de scripts extras de seed na aplicação.

Exemplo prático: um arquivo 01-init.csh cria o database e containers; 02-load.csh insere dados de exemplo. Ao montar a pasta local em /init com a variável ENABLE_INIT_DATA=true, o emulador já sobe com dados prontos para teste.

Copiardocker run --name emulator --rm -e ENABLE_INIT_DATA=true \
  -v "$(pwd):/init" -p 8081:8081 -p 1234:1234 \
  mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest

Esse mecanismo é ideal para:

• CI integration tests: cada job começa com um dataset idêntico, sem polling de readiness.
• Reset de ambiente local: com --rm e uma pasta /init, um comando restaura o estado inicial.
• Demos e tutoriais: scripts de fixture podem ser distribuídos junto com o código.
• Bug repros: um conjunto de scripts que recria exatamente o estado problemático.

Vector search: IA local sem custo de nuvem

O emulador agora suporta vector search, permitindo construir e iterar workloads de RAG e busca semântica inteiramente na máquina local. Basta definir uma política de embedding no container, criar um índice vectorial e escrever os embeddings junto com os documentos.

Copiar{
  "vectorEmbeddingPolicy": {
    "vectorEmbeddings": [
      { "path": "/embedding", 
        "dataType": "float32", 
        "distanceFunction": "cosine", 
        "dimensions": 1024 }
    ]
  }
}

Com a função VectorDistance(), consultas semânticas podem ser executadas localmente. Um exemplo prático usa LangChain e Ollama para embeddings: carregue dados, execute queries como "show me an example of a vector embedding policy" e receba resultados ranqueados por similaridade — tudo sem sair do laptop.

Health probes e observabilidade

O emulador expõe endpoints de health check na porta 8080: /alive (liveness), /ready (readiness) e /status (detalhado). Antes, scripts de CI precisavam parsear logs para saber quando o gateway estava pronto — agora, probes HTTP eliminam essa fragilidade.

Além disso, o suporte ao OpenTelemetry Protocol (OTLP) permite exportar métricas de performance (taxa de requisições, tempo de execução de queries, utilização de recursos) para qualquer backend compatível. Com a flag --enable-console, a telemetria é impressa no stdout para debug rápido.

Cobertura de API ampliada

A superfície de APIs suportadas agora inclui change feed, batch operations, JOINs, queries de range e agregação, subdocument queries, hierarchical partition keys, TTL e operadores de string e array. Endpoints não essenciais (offers, users, permissions) retornam status code válidos sem executar a operação, evitando quebras no código da aplicação.

Perguntas Frequentes

• O emulador vNext substitui completamente o uso de uma conta live do Azure Cosmos DB?

  • Sim, para cenários de desenvolvimento e testes locais e integração contínua. Ele oferece uma instância local que suporta as principais APIs (SQL, MongoDB, Cassandra, Gremlin, Table) e funcionalidades como change feed, batch operations, JOINs, TTL e vector search. No entanto, para testes de throughput, SLA e escalabilidade reais, ainda é necessário uma conta live.

• Como o bootstrap via scripts .csh melhora a experiência de CI/CD?

  • Você pode montar um diretório /init com scripts .csh que são executados automaticamente antes do emulador ficar pronto. Isso permite que cada job de CI comece com um dataset idêntico e determinístico, eliminando a necessidade de scripts de seed no código da aplicação e reduzindo a latência dos pipelines.

• O suporte a vector search no emulador é suficiente para desenvolver aplicações RAG localmente?

  • Sim. O emulador suporta políticas de embedding, índices vectoriais (DiskANN) e a função VectorDistance(). Combinado com modelos locais via Ollama e frameworks como LangChain, é possível iterar sobre retrieval aumentado e buscas semânticas inteiramente na máquina do desenvolvedor, sem custos de nuvem.

• Quais são os ganhos com o suporte a OpenTelemetry no emulador?

  • Com a flag --enable-otlp, o emulador exporta métricas de performance (taxa de requisições, tempo de execução de queries, utilização de recursos) para qualquer backend OTLP. Isso permite monitorar o comportamento da aplicação localmente com as mesmas ferramentas usadas em produção, facilitando a detecção precoce de gargalos.

• O emulador funciona em arquiteturas ARM64 (Apple Silicon, etc.)?

  • Sim. A imagem Docker do emulador vNext é distribuída para Linux, macOS e Windows, tanto em x64 quanto ARM64. Isso é especialmente relevante para times brasileiros que adotaram Apple Silicon, eliminando a necessidade de emulação adicional.

---

Artigo originalmente publicado por Abhishek Gupta em Azure Updates - Latest from Azure Charts.