“If you cannot measure it, you cannot improve it.” (Lord Kelvin)

“In God we trust; all others must bring data. (W. Edwards Deming)

Errors using inadequate data are much less than those using no data at all (Charles Babbage)

Em geral, as afirmações fazem sentido, mas frases rápidas não tratam de nuances. Ao aplicar a cultura “data driven”, vejo dois erros comuns que são pouco discutidos:

• ignorar as limitações dos dados, confiar em métricas poucos representativas;
• interpretar os dados de forma simplória, caindo em erros por análises rasas.

Quando percebo que esses problemas podem ocorrer – tenho um comportamento contra-intuitivo como cientista de dados – que é evitar trazer números. Pelo menos, tento trazê-los de forma que destaque essas limitações. Não tenho como controlar a interpretação dos resultados, mas tento destacar as limitações e pontos de atenção.

De forma alguma, quero questionar a cultura “data driven” que se criou na última década: essa é uma discussão de um problema menor, no contexto de uma mudança muito positiva. Antes errar tentando usar dados, que nem tentar.

A falsa confiança da matemática

Existe uma discussão filosófica sobre a matemática ter sido criada ou descoberta. Um argumento, a favor do segundo cenário, é sua relação com as ciências naturais¹:

Se o π foi inventado para estudar o perímetro do círculo, então por que aparece na lei da distribuição normal de Gauss, um dos princípios fundamentais da estatística? O que perímetro do círculo tem a ver com estudo de populações e pesquisas de opinião?

Independente da sua opinião sobre essa discussão, a efetividade da matemática nas ciências naturais é indiscutível. E o grande sucesso das ciências naturais nos últimos séculos, gerou o efeito de “inveja da física”, em que outras áreas do conhecimento tentam replicar o uso de métodos matemáticos das ciências naturais.

Por que economistas são mais influentes que sociologistas? Justamente por utilizar muitos modelos matemáticos, a Economia parece mais próxima das ciências naturais que outras áreas de humanas. O que não significa que realmente esteja, mas mesmo sem resultados consistentes, o uso de linguagem matemática inescrutável é o suficiente para trazer credibilidade.

Modelar e representar algo matematicamente não é garantia de nada, não é somente sobre a qualidade da modelagem ou disponibilidade de dados, mas principalmente do quão bem a matemática se aplica ao problema. A questão não é a falta de capacidade dos economistas em modelar, mas a natureza do problema que estão lidando.

Preciso de um número, somente um número

Se você já respondeu a pergunta “Você recomendaria X para um amigo ou familiar?” em alguma pesquisa de satisfação, é porque a empresa adotou a metodologia Net Promoter Score (NPS). Ela foi popularizada por um artigo publicado na HBR em 2003, com o chamativo título “The One Number You Need to Grow”. A premissa era ambiciosa:

The good news is: you don’t need expensive surveys and complex statistical models. You only have to ask your customers one question: “How likely is it that you would recommend our company to a friend or colleague?” The more “promoters” your company has, the bigger its growth.

No próprio artigo, são discutidas limitações da métrica, como em cenários de monopólio ou que o consumidor não tem opções (e.g. saneamento básico, sistemas corporativos). A métrica teve uma grande adoção do mercado – surgiram estudos questionando a superioridade do NPS (1, 2) em relação às demais métricas de satisfação – mas não parece ter impactado em sua fama.

O foco não é criticar o NPS, mas ilustrar o apelo que métricas simples e ambiciosas têm. O mundo digital inundou as empresas e as nossas vidas com métricas e dados sobre tudo, mas é humanamente impossível organizar e extrair sentido sem ajuda. A “solução” é simplificar esses dados a qualquer custo e reduzir tudo a um valor mágico.

A WHOOP calculou que Cristiano Ronaldo tem 28 anos de “idade biológica”, usando sensores básicos e não invasivos das suas pulseiras, encontrados em qualquer relógio inteligente. São dados extremamente limitados que alimentam um modelo proprietário, mas que foi publicado em vários locais (1, 2, 3) como uma verdade absoluta, com o próprio atleta dizendo “The data doesn’t lie”.

Quando questiono o NPS, não é porque eu tenho uma proposta melhor ou que deveríamos abandoná-lo, a ideia é apenas ter atenção às limitações e tomar cuidado ao transformar esse tipo de métrica em KPIs e OKRs. Prever crescimento de uma empresa e avaliar satisfação do cliente – são problemas abstratos, cheio de nuances e contextual – é muito difícil que um único indicador dê conta de representar bem esses problemas.

É uma posição impopular, tanto com as áreas de negócio quanto com os parceiros da área de dados, quando eu questiono se deveríamos focar tanto em determinados números. Eu entendo a premissa de que usar um número – impreciso e/ou pouco representativo ainda é melhor que nada – mas é muito difícil apresentar um número e depois dissuadir as pessoas de confiarem cegamente nele.

Ao trazer um número e colocar vários ressalvas para utilizá-lo, as pessoas interpretam como falta de confiança. A limitação pode ser inerente ao problema, mas é algo difícil de explicar, especialmente para uma audiência menos especializada. Sempre que você titubear, haverá alguém vendendo números mágicos e muito apetite para utilizá-los.

Não é tão simples quanto parece

Um outro problema comum ao utilizar dados, é fazer leitura errada ou limitada das métricas. Uma questão sensível no Brasil, que ilustra muito bem esse problema, são discussões sobre renda.

As pessoas ficam surpresas, ao saberem que estão entre os 10% ou 5% mais ricos do país. É complicado compreender o que significa alguém ser bilionário, existir pessoas que estão 3 ordens de grandeza acima do limiar dos top 5%: esse tipo de coisa não existe em uma curva normal, nenhuma pessoa tem 200 metros de altura por exemplo. Distribuição de renda é um problema complexo de modelar, com números que fogem da nossa compreensão intuitiva sobre números.

Programadores aprenderam a olhar tempos de reposta sem assumir distribuição normal, é uma prática acompanhar percentis altos (.e.g. P95 e P99) para ter uma visão mais concreta do cenário. Mas ainda é muito difícil explicar como funciona: o tempo médio de reposta da API é 50ms, mas que não é raro ficar em 20ms ou passar de 500ms. Esses valores não encaixam na intuição de média e desvio padrão que as pessoas aprendem, tendo como perspectiva uma gaussiana.

Para lidar com dados fora da distribuição normal, é importante avaliar o cenário com boxplot, histograma e testes de normalidade. Simplesmente olhar métricas como média e desvio padrão, pensando em uma gaussiana, pode levar a uma interpretação errada da situação. Mas quantas pessoas sabem o que é um boxplot?

É fundamental que a área de negócio faça a interpretação dos dados – algo que os especialistas em dados podem e devem ajudar – mas em última instância, não é algo que pode ser completamente delegado para o time de ciência de dados.

Quando o mundo cometeu esses erros

Um cenário que exemplifica ambos os desafios, foram os modelos epidemiológicos utilizados durante a pandemia de COVID-19. Os modelos de compartimento são baseados em derivadas parciais, em que a curva de infecção é governada pela taxa \(R_{t}\): um indivíduo infecta quantas outras pessoas em um tempo \(t\) ?

Por esses modelos, lidar com a pandemia era uma questão de achatar a curva, reduzindo o \(R_{t}\) para os sistemas de saúde suportarem a demanda. Achatar a curva significava ter uma pandemia mais longa, mas com um pico de infecção menor.

Os gráficos gerados por esses modelos foram vistos como exemplos de “storytelling” e tomada de decisão com dados , mas na prática as coisas foram diferentes. Percebeu-se que esse modelo não respondia às perguntas que a população fazia e nem serviam como preditor.

Podia-se estimar um \(R_{t}\) alvo, mas como medir esse número e como chegar nesse alvo? Percebeu-se que \(R_{t}\) era uma média, mas pessoas e contextos outliers poderiam ser o grande problema. Além disso, a nossa capacidade de diagnosticar a doença tem limitações importantes, era muito difícil saber ao certo quantas pessoas estavam infectadas em um determinado momento.

Além da dificuldade em medir o \(R_{t}\) real, o modelo de compartimentos não explicava a realidade do sistema de saúde. O mesmo \(R_{t}\) – considerando um asilo ou um vestiário de futebol profissional – traziam impactos práticos muito distintos no sistema de saúde. Outros parâmetros, como tempo de recuperação e re-infecção mudavam a todo momento: mutações do virus, tratamentos, prevenções e vacinas.

Era um cenário muito complexo, para um modelo muito simples. Uma pandemia global não é como uma doença infecciosa em ambiente natural: animais não se previnem, não fazem viagens intercontinentais, não procuram tratamentos e nem desenvolvem vacinas.

Apesar de ser impossível parametrizar os modelos corretamente em grande escala, a dinâmica geral de infecção descrita pelos modelos, ainda fazia sentido: achatar a curva era um plano, mesmo que não fosse possível estimar com precisão os parâmetros do modelo. Em contextos limitados e para projeções, esses modelos e o \(R_{t}\) eram úteis.

Ou seja, tínhamos métricas e um modelo insuficiente para lidar com a complexidade da situação. Além disso, interpretar os resultados e as implicações, era algo muito complexo para a população e tomadores de decisão.

Conclusão

Após anos de incentivo à tomada de decisão baseada em dados, talvez seja um tabu questionar seu uso. Todo modelo é uma aproximação e não uma realidade, como diria o “ditado” da estatística: todos os modelos estão errados, mas alguns são úteis.

Sou a favor de usar dados e modelos sempre que possível, mas não virar uma muleta para toda tomada de decisão. Infelizmente, nem sempre é possível trabalhar com dados, especialmente em produtos muito inovadores ou cenários em que pesquisa e testes são muito caros. É aceitar que é necessário tomar algumas decisões por convicção ou intuição, ao invés de forçar o uso de dados e modelos insuficientes.

Steve Jobs – talvez a maior referência dos “produteiros” – era famoso por não ser o maior entusiasta de pesquisas de mercado (e nem de consultores). Nenhum dashboard ou modelo, iria corroborar com a ideia de fazer um smartphone sem teclado em 2007. Muito pelo contrário, já que o produto na época era restrito ao mercado corporativo, com foco em comunicação via texto ao invés de consumo de conteúdo de hoje em dia. O valor da ideia era justamente ir contra o restante do mercado, não fazer algo incremental.

Os riscos existem: você provavelmente não tem a visão do Steve Jobs, nem os recursos da Apple e não trabalha em uma empresa com o mesmo apetite a risco. Mas forçar um número que justifique uma decisão revolucionária e arriscada, não vai mitigar seus riscos, mas pode mascará-los.

A eterna promessa do low code, a nova do vibe code

A promessa do vibe code é muito similar ao low code, tornar desenvolvimento de software acessível para quem não sabe programar. Mas, ao invés de inventar uma nova linguagem visual baseadas em workflows, a ideia é que os agentes consigam traduzir especificações em linguagem natural para código.

Eu já discuti sobre os motivos do low code sempre ficar aquém das expectativas criada pelos vendedores – alguns desses problemas são mitigados com vibe coding, outros persistem – mas a limitação fundamental é a mesma: a grande dificuldade não é programar, mas lidar com a complexidade inerente de grandes sistemas.

Os problemas que um ERP precisa resolver são bem conhecidos (e.g. gestão de estoque, cálculos de imposto, contabilidade) e não exigem conhecimentos em tópicos avançados de computação. Só que cada empresa tem um ERP diferente, seguindo a “lei de Conway”:

Organizations which design systems (in the broad sense used here) are constrained to produce designs which are copies of the communication structures of these organizations.

Suponha uma nova regra para cálculo imposto – o desafio não é compreender e codificar a regra – é saber em que parte do sistema esse cálculo é feito, identificar os impactos da mudança e desenhar como será alterado. O padrão é que profissionais mais experientes e arquitetos façam o desenho da solução, profissionais menos experientes fazem a codificação.

No “mundo real”, especificar o problema é bem mais complexo do que implementar. Os agentes são muito efetivos na implementação de algo específico, mas ainda são bem limitados para tratar problemas vagos. Existem agentes mais ambiciosos como Devin, que se propõe a trabalhar a partir de um chamado, mas os relatos são de experiências frustrantes:

But that’s the problem - it rarely worked. Out of 20 tasks we attempted, we saw 14 failures, 3 inconclusive results, and just 3 successes. More concerning was our inability to predict which tasks would succeed. Even tasks similar to our early wins would fail in complex, time-consuming ways. The autonomous nature that seemed promising became a liability - Devin would spend days pursuing impossible solutions rather than recognizing fundamental blockers.

O vibe code compartilha da mesma limitação fundamental do low code, mas seria injusto dizer que ele não é um avanço em outros aspectos. O principal avanço é trabalhar com código em linguagens e frameworks populares, ao invés de DAGs especificados em uma tecnologia proprietária.

As grandes evoluções em linguagens, arquiteturas e metodologias – orientação a objetos, microsserviços, data mesh, devops – surgiram para (tentar) domar a entropia dos sistemas. As ferramentas de low code são ótimas para demonstrações simples, mas oferecem muito pouco para controlar a complexidade.

Mesmo com pessoas capacitadas e experientes, acabamos com sistemas insustentáveis que precisam ser substituídos. Pessoas leigas gerando milhares de linhas de código – como podemos ver com sistemas feito sem boas práticas, planilhas e ferramentas low code – é apenas acelerar esse processo.

Por melhor que seja o código, qualquer linha a mais significa débito técnico: mais possibilidades de falhas de segurança, erros de lógica e tempo para entender o sistema. Gerar muito código com vibe code é fácil, mas pode ser uma armadilha disfarçada de produtividade.

Reduzindo expectativas

A frustração é proporcional às expectativas criada, até os mais entusiastas concordam que “IA” ficou aquém: o Chat GPT foi lançado em Novembro de 2022, três anos depois e não temos um mundo tão diferente assim. Deixando as expectativas de lado, é algo que tenho usado regularmente para programação e certamente sentiria falta se perdesse acesso.

Nesse cenário de hype infinito, talvez a opinião de alguém que tem preguiça disso tudo e até um pouco de “ranço”, seja interessante: uso apenas o chat como um Stack Overflow melhorado. Não fico explorando diferentes modelos, nunca usei IDEs otimizadas para agentes e nem perco muito tempo com “prompt engineering”.

A minha primeira experiência com IA foi usando o auto completar, algo que eu logo desisti. Algumas vezes o auto completar parecia estar lendo minha mente, mas na maioria dos casos era uma distração perigosa:

• código verboso demais, com tratamentos de erro desnecessários e padrões diferentes do restante do código;

• geração de código para problemas que eu sei resolver, perdia mais tempo lendo a sugestão que implementando sem auxílio;

• erros bobos, como um nome de variável ou definição de constante, que podem ser identificados muito tarde no processo de desenvolvimento.

Por isso, eu prefiro ir proativamente ao chat quando faz sentido. Eu testei o modo agente do VS Code, mas não gostei muito de precisar revisar as mudanças, prefiro ler a resposta e editar manualmente os arquivos. Era muito trabalhoso, quando o agente fazia mudanças parcialmente corretas, para aceitar apenas o que eu desejava.

Pedir via chat é o jeito mais básico de aplicar IA, nada que não conseguiria resolver olhando a documentação e Stack Overflow. A grande vantagem é o contexto: não preciso ir para um navegador tirar dúvidas e o agente responde melhor com acesso ao código. Não perco o flow, porque não preciso sair da IDE para pesquisar e as soluções vêm mais prontas.

A estrutura principal do código eu prefiro fazer manualmente, o que eu peço são trechos de código para resolver problemas pontuais (e.g. como sortear uma posição do array, conectar ao banco de dados e fazer uma requisição HTTP). Quando preciso trabalhar em outras linguagens ou com novas bibliotecas, uso mais regularmente e isso deixa o aprendizado mais fluído.

Para códigos descartáveis, eu não vejo problemas em delegar completamente para IA. Códigos para gerar gráficos ou scripts que serão utilizados uma vez, não faço questão de cuidar da estrutura. Além de códigos menos críticos, problemas repetitivos em projetos como scaffold de modelos e criação de mocks para testes, sou menos criterioso com o código gerado.

Se eu não pudesse mais utilizar AI para programar, eu perderia produtividade? Imagino que de forma marginal, mas certamente teria uma percepção de menos produtividade. As tarefas que delego são as coisas chatas e repetitivas, que talvez não tomem muito tempo, mas é justamente o que não quero fazer.

É muito comum programadores discutirem avidamente, qual linguagem ou IDE é mais produtiva, mas existe zero rigor ou mesmo dados para essas afirmações. E tudo bem, é importante que você se sinta bem com as suas ferramentas, não precisa de um resultado científico que comprove isso. Esse anseio moderno de metrificar tudo, gera algo pior que não ter métricas: usar números pouco representativos como verdade absoluta.

Como eu disse, tenho um pouco de preguiça de explorar mais e faço um uso básico. Já li relatos de pessoas que viraram quase orquestradoras de agentes, mas não me convenci de que se aplica bem ao meu dia-a-dia. Se existir um jeito maravilhoso de usar IA para programação, tenho certeza que chegará em mim de alguma forma.

Vamos chegar lá?

Pessoalmente, não tenho expectativas que esse cenário vá mudar no futuro próximo, ainda estaremos presos nessa situação: IA ajudará cada vez mais a programar, mas ainda não consegue descobrir o que deve ser programado. Posso estar errado, mas novamente: eu vou saber, se existir um jeito incrível de utilizar IA para programação.

Minha preocupação atual, é mais com os iniciantes. Já era um problema pessoas que copiavam código do Stack Overflow sem entender, caindo em um máximo local: consegue fazer algumas tarefas básicas, mas não evolui por estar copiando sem entender. O vibe code te leva muito mais longe sem entender as coisas, mas é ruim pensando em evolução profissional trabalhar dessa forma.

A minha maior dúvida é como o mercado ficaria, se uma possível bolha de IA estourasse. Eu não sei quanto custa para manter os maiores modelos rodando, quantos usuários seriam necessários e qual o valor a ser cobrado. Quais modelos seriam financeiramente viáveis? Utilizaríamos modelos locais menores?

Talvez o cenário mude muito – mas ao final de 2025 – ainda utilizo IA como mais um recurso legal da IDE.

Seguindo meus próprios princípios, procurei saber os conceitos por trás dessas soluções e descobri sobre o HNSW (Hierarchical Navigable Small World). É um algoritmo muito interessante – que junta os conceitos de skip-list e uma estrutura de grafos – para oferecer complexidade \(log (N)\) na busca de embeddings.

Como esse algoritmo funciona e por que ele nem sempre retorna o resultado ótimo?

O problema

Uma das aplicações mais comuns para o uso de embeddings são soluções baseadas em RAG, no qual a etapa de retrieval é uma busca vetorial para alimentar a geração de resposta. É importante notar que a “busca vetorial” é, na verdade, um problema de ranqueamento: a proposta é ordernar o conteúdo por relevência e não filtrar o conjunto de dados por alguma chave de busca.

É um problema trivial para poucos vetores – basta calcular o produto interno entre o vetor da consulta e os vetores do conjunto de dados – mas não escala bem. Esse cálculo demanda uma matriz contendo todos os embeddings do conjunto de dados em memória, o que torna essa solução inviável para grandes conjuntos de dados.

A proposta do HNSW é análoga a um índice de banco de dados, criar uma estrutura de dados adicional para otimizar a recuperação de informação. A estrutura é uma hierarquia de grafos, em que cada nó representa um documento no conjunto de dados e as arestas são geradas por heurísticas com base na proximidade dos vetores.

Diferente de outras estruturas de índice, ela não garante o resultado ótimo: a depender dos parâmetros de busca e criação, é possível obter respostas diferentes para uma mesma consulta e mesmo conjunto de vetores. A construção do grafo também tem processos estocásticos, construir um HNSW com os mesmos dados e parâmetros, não garante uma mesma estrutura final.

O HNSW é uma estrutura de dados com aspectos de modelo de machine learning: a performance precisa ser avaliada tanto da perspectiva de computação como pelo prisma de qualidade resultados. Erros de configuração não atrapalham apenas o tempo de resposta, mas a qualidade dela também.

Criando os pequenos mundos

Os “mundos pequenos” do HNSW são as camadas da hierarquia de grafos da estrutura. Ao inserir um ítem, a hierarquia do grafo é escolhida de forma estocástica, usando a seguinde função:

\[ \lfloor -ln(U(0,1)) \cdot m_{l} \rfloor \]

sendo \(U(0,1)\) uma distribuição uniforme no intervalo \([0,1]\) e \(m_{l}\) um hiperparâmetro no intervalo \([0,1]\). Abaixo, a implementação em Python dessa etapa:

class HNSW:
    ...
    def __init__(self, m_max: int, m_max0: int, ef_construction: int, m_l: float):
        self.layers: list[Layer] = []
        self.m_max = m_max
        self.m_max0 = m_max0
        self.m_l = m_l
        self.ef_construction = ef_construction
        self.entrypoint: str | None = None

    def _get_level(self) -> int:
        return int(np.floor(-np.log(np.random.uniform()) * self.m_l))
    
    def insert(self, key: str, value: list[float]):
        
        level = self._get_level()

        ...
    ...

A estrutura do HNSW começa com zero camadas, elas são criadas à medida em que se faz necessário. Por exemplo, se o nó foi sorteado para a camada 3 e existe apenas uma camada, as duas camadas adicionais serão criadas com esse nó:

class HNSW:

    def __init__(self, m_max: int, m_max0: int, ef_construction: int, m_l: float):
        self.layers: list[Layer] = []
        self.m_max = m_max
        self.m_max0 = m_max0
        self.m_l = m_l
        self.ef_construction = ef_construction
        self.entrypoint: str | None = None

    def _get_level(self) -> int:
        return int(np.floor(-np.log(np.random.uniform()) * self.m_l))

    def _create_layer(self):
        self.layers.append(Layer())

    def insert(self, key: str, value: list[float]):

        max_level = len(self.layers) - 1
        level = self._get_level()

        while max_level < level:
            self._create_layer()
            max_level = len(self.layers) - 1
        ...

Caso o nó a ser incluído seja sorteado para uma camada inferior, é necessário iniciar da camada superior e ir descendo até encontrar um nó que esteja presente na camada sorteada:

def insert(self, key: str, value: list[float]):
    ...
    entrypoint: str = self.entrypoint

    for level in reversed(range(level, max_level)):
        entrypoint, *_ = self.layers[level].search(value, 1, entrypoint)
    ...

Ao chegar na camada sorteada, ela deva ser atualizada e todas as que estão abaixo da mesma. O processo consiste em selecionar os vizinhos aos quais esse nó será conectado, restrito a um hiperparâmetro \(m_{max}\). É criada uma conexão com esses vizinhos, caso o vizinho acabe com mais conexões que \(m_{max}\), eles são re-selecionados utilizando o mesmo método.

def insert(self, key: str, value: list[float]):

    max_level = len(self.layers) - 1
    level = self._get_level()

    while max_level < level:
        self._create_layer()
        max_level = len(self.layers) - 1

    entrypoint: str = self.entrypoint

    for level in reversed(range(level, max_level)):
        entrypoint, *_ = self.layers[level].search(value, 1, entrypoint)

    for level in reversed(range(min(level, max_level) + 1)):

        layer = self.layers[level]
        layer.add_node(key, value)

        if len(layer.nodes) == 1:
            self.entrypoint = key
        else:
            neighbors = layer.select_neighbors_heuristic(
                key,
                layer.search(value, self.ef_construction, entrypoint),
                self.m_max,
            )

            for neighbor in neighbors:

                layer.connect(key, neighbor)
                neighbor_neighbors = layer.get_neighbors(neighbor)

                m_max = self.m_max0 if level == 0 else self.m_max

                if len(neighbor_neighbors) > m_max:
                    layer.set_neighbors(
                        neighbor,
                        layer.select_neighbors_heuristic(
                            neighbor,
                            neighbor_neighbors,
                            m_max,
                        ),
                    )

Nesse processo de inclusão, existem vários hiperparâmetros que impactam no resultado da estrutura:

• m_l: constante que altera a probabilidade de gerar uma nova camada. As camadas são necessárias para manter a complexidade \(log(N)\), mas elas ficam ineficientes se existir muita sobreposição de nós entre as camadas.

• m_max e m_max0: indicam a quantidade de conexões que um nó pode ter, o m_max0 é um valor que se aplica apenas a camada mais inferior. Quanto mais conexões existir, maior a probabilidade de obter o resultado ótimo nas consultas. Por outro lado, um grafo com muitas conexões é mais demorado para navegar e ocupa mais espaço em memória.

• ef_construction: é um parâmetro utilizado no método Layer.search, que indica a quantidade de vizinhos a ser retornado pela busca. Quanto mais elementos, mais chances de obter melhores resultados na etapa de conectar os vizinhos, por outro lado demanda mais processamento.

A definição desses parâmetros dependerão da características do conjunto de dados, se tornando um problema muito similar com a escolha de hiperparâmetros para modelos de machine learning.

Escolhendo a vizinhança

O método mais trivial para escolher os vizinhos, é fazer uma simples busca pelos \(m\) mais próximos a partir de uma lista de candidatos:

class Layer:
    ...
    @staticmethod
    def distance(x: list[float], y: list[float]) -> float:
        return sqrt(sum([(x - y) ** 2 for x, y in zip(x, y)]))
    ...
    def select_neighbors(self, key: str, candidates: list[str], m: int) -> list[str]:

        value = self.nodes[key]

        best_candidates = sorted(
            [
                (Layer.distance(v, self.nodes[c]), c)
                for v, c in product([value], candidates)
                if c != key
            ],
            key=lambda x: x[0],
        )

        return [c for _, c in best_candidates][:m]

Apesar de funcional, essa implementação ingênua pode criar vizinhanças isoladas, inacessíveis a depender do ponto de entrada da busca. Para mitigar esse cenário, os criadores do algoritmo propuseram uma seleção heurística:

class Layer:
    ...
    @staticmethod
    def distance(x: list[float], y: list[float]) -> float:
        return sqrt(sum([(x - y) ** 2 for x, y in zip(x, y)]))
    ...

    def select_neighbors_heuristic(
        self,
        key: str,
        candidates: list[str],
        m: int,
        extend_candidates: bool = True,
        keep_pruned_connections: bool = True,
    ) -> list[str]:

        value = self.nodes[key]
        neighbors = set([])
        working_candidates = set([c for c in candidates if c != key])

        if extend_candidates:
            for candidate in candidates:
                for candidate_neighbor in self.edges[candidate]:
                    if (
                        candidate_neighbor not in working_candidates
                        and candidate_neighbor != key
                    ):
                        working_candidates.add(candidate_neighbor)

        discarded_candidates = set([])

        while len(working_candidates) > 0 and len(neighbors) < m:

            nearest_wc = self._get_nearest(value, working_candidates)
            working_candidates.remove(nearest_wc)

            nearest_wc_distance = self.distance(self.nodes[nearest_wc], value)

            add_candidate = bool(
                sum(
                    [
                        nearest_wc_distance < self.distance(value, self.nodes[neighbor])
                        for neighbor in neighbors
                    ]
                )
            )

            if add_candidate or len(neighbors) == 0:
                neighbors.add(nearest_wc)
            else:
                discarded_candidates.add(nearest_wc)

        if keep_pruned_connections:
            while len(discarded_candidates) > 0 and len(neighbors) < m:
                nearest_candidate = self._get_nearest(value, discarded_candidates)
                discarded_candidates.remove(nearest_candidate)
                neighbors.add(nearest_candidate)

        return list(neighbors)

Se o parâmetro extend_candidates for verdadeiro, a seleção inclui os “vizinhos dos vizinhos” na busca. Com esses candidatos extras, a seleção pode criar conexões entre grupos de vetores que antes ficariam inacessíveis. Se o parâmetro extend_candidates for falso, select_neighbors e select_neighbors_heuristic são o mesmo algoritmo.

O parâmetro keep_pruned_connections é uma forma de não desprezar conexões válidas, já que a estratégia gulosa de seleção pode acabar descartando vizinhos eleígiveis no meio do caminho.

A busca

A busca é feita a partir da camada superior com menos nós, até chegar a camada inferior que contém todos os nós do conjunto.

class HNSW:
    ...
    def search(
        self, query: list[float], k: int, ef_search: int
    ) -> list[tuple[str, list[float]]]:

        if self.entrypoint is None:
            return []

        entrypoint = self.entrypoint

        for layer in reversed(self.layers):
            keys = layer.search(query, ef_search, entrypoint)
            entrypoint, _ = min(
                [(key, Layer.distance(query, layer.nodes[key])) for key in keys],
                key=lambda x: x[1],
            )

        layer, *_ = self.layers
        keys = layer.search(query, ef_search, entrypoint)

        k_keys = sorted(
            [(key, Layer.distance(query, layer.nodes[key])) for key in keys],
            key=lambda x: x[1],
        )[:k]

        return [(key, layer.nodes[key]) for key, _ in k_keys]
    ...

O parâmetro ef_search indica quantos ítens devem ser considerados: quanto maior esse valor, maior a probabilidade de chegar na solução ótima. Entretanto, o processo de busca é mais caro computacionalmente. O parâmetro k é a quantidade de ítens que devem ser retornados.

A busca em uma camada é um processo guloso, que procura os vizinhos mais próximos a partir de um ponto de entrada. Para evitar ciclos, há uma lista de nós visitados:

class Layer:
    ...
    @staticmethod
    def distance(x: list[float], y: list[float]) -> float:
        return sqrt(sum([(x - y) ** 2 for x, y in zip(x, y)]))

    def _get_nearest(self, query: list[float], nodes: Iterable[str]) -> str:

        nearest = ("", sys.float_info.max)

        for node in nodes:

            node_distance = Layer.distance(query, self.nodes[node])
            _, smaller_distance = nearest

            if node_distance < smaller_distance:
                nearest = (node, node_distance)

        return nearest[0]

    def _get_furthest(self, query: list[float], nodes: Iterable[str]) -> str:

        furthest = ("", -sys.float_info.max)

        for node in nodes:

            node_distance = Layer.distance(query, self.nodes[node])
            _, bigger_distance = furthest

            if node_distance > bigger_distance:
                furthest = (node, node_distance)

        return furthest[0]
    ...
    def search(
        self, query: list[float], elements_to_return: int, entrypoint: str
    ) -> list[str]:

        visted = set([entrypoint])
        candidates = set([entrypoint])
        nearest_neighbors = set([entrypoint])

        while len(candidates) > 0:

            nearest_node = self._get_nearest(query, candidates)
            candidates.remove(nearest_node)

            furthest_node = self._get_furthest(query, nearest_neighbors)

            if Layer.distance(query, self.nodes[nearest_node]) > Layer.distance(
                query, self.nodes[furthest_node]
            ):
                break

            for node in self.edges[nearest_node]:

                if node not in visted:

                    visted.add(node)
                    furthest_element = self._get_furthest(query, nearest_neighbors)

                    if (
                        Layer.distance(query, self.nodes[node])
                        < Layer.distance(query, self.nodes[furthest_element])
                        or len(nearest_neighbors) < elements_to_return
                    ):

                        candidates.add(node)
                        nearest_neighbors.add(node)

                        if len(nearest_neighbors) > elements_to_return:
                            nearest_neighbors.remove(furthest_element)

        return list(nearest_neighbors)

E como escolher os parâmetros?

Algo que eu sempre digo: se existisse uma forma trivial de escolher os hiperparâmetros, eles seriam constantes e não parâmetros ou escolhidos automaticamente. Eu pensei em explorar esse aspecto nesse post, mas a conclusão é que não devo utilizar essa estrutura para o problema que estou tratando hoje: fazer busca vetorial em pequenos subconjuntos. É mais eficiente filtrar o conjunto com um índice tradicional, para depois ordenar sem uma estrutura adicional como o HNSW.

Eu só pude chegar a essa conclusão, porque entendi como funciona uma busca vetorial. Caso eu precise trabalhar com tunning de um RAG em milhões de registros, já sei quais parâmetros eu devo olhar a depender do problema que estou enfrentando (e.g. tempo de construção, tempo de busca, consumo de memória) e das características dos meus dados. Assim como ajustar os parâmetros de uma random forest por exemplo, é importante realmente entender a dinâmica dos parâmetros do HNSW, para não perder tempo com uma tentiva e erro sem direção.

Eu implementei o algoritmo apenas para fins didáticos, nem tenho certeza de sua corretude, mas é um jeito que me ajuda a realmente entender os problemas. Talvez, eu retome esse assunto de como escolher os parâmetros, mas é um assunto que merece outro post.

Nessa posição, trabalho muito em conjunto com os cientistas de dados, mas atuando como programador. Qualquer desenvolvedor, que precisou colocar em produção – um modelo implementado em um único arquivo chamado Untitled (7) Copy.ipynb – sabe que alguns cientistas precisam aprender muito sobre as práticas de programação. Por outro lado, trabalhar com cientistas me ensinou a ver os desafios de programação com outros olhos.

Saber (somente) a API, não é saber

Um dos meus pontos fracos como cientista de dados, é não ter muita profundidade teórica. Eu tenho a intuição de como um SVM funciona, mas não saberia implementar a otimização e nem entendo as partes mais sofisticadas como o kernel trick. Apesar de ser um modelo complexo de entender, é muito simples utilizá-lo no scikit-learn, mais trivial impossível:

from sklearn import svm
X = [[0, 0], [1, 1]]
y = [0, 1]
clf = svm.SVC()
clf.fit(X, y)

Não posso dizer que sei usar o SVM por conseguir treiná-lo usando uma biblioteca. Já como programador, é normal usar bibliotecas e abstrair completamente a implementação, conquanto que tenha o comportamento esperado. Essa se tornou a abordagem padrão, tanto que o MIT trocou Scheme por Python em seu curso introdutório, para refletir esse cenário:

In 1980, good programmers spent a lot of time thinking, and then produced spare code that they thought should work. Code ran close to the metal, even Scheme — it was understandable all the way down. […] But programming now isn’t so much like that, said Sussman. Nowadays you muck around with incomprehensible or nonexistent man pages for software you don’t know who wrote. You have to do basic science on your libraries to see how they work, trying out different inputs and seeing how the code reacts. This is a fundamentally different job, and it needed a different course.

Essa estratégia tende a funcionar bem, mas algumas vezes faz-se necessário entender a implementação, para fazer um troubleshoot ou resolver problemas de desempenho. Eu discuti nesse post, como esse problema é recorrente na engenharia de dados: os tutoriais são super amigáveis e tudo funciona bem no começo, mas as coisas podem se complicar muito rapidamente.

Eu brinco que a curva de aprendizado de Apache Spark é suave, especialmente se o uso se limitar a queries SQL, mas de repente vira algo super avançado quando é necessário lidar com problemas de serialização e erros internos em Scala.

Não estou sugerindo que se tenha conhecimento profundo sobre todas as ferramentas e frameworks, é simplesmente impossível e os ganhos práticos seguem a lei dos rendimentos decrescentes. Minha sugestão é seguir o conselho do Martin Kleppman, autor do livro “Design Data Intensive Applications”, de se preocupar em ter uma noção de como as coisas estão funcionando por trás das abstrações:

Learn just enough abot the internals of the tools you are using, so that you have a reasonable mental model of what’s going on there. You don’t need to be able to, like, modify of the Kafka yourself, but I think having just enough of an idea of the internals that […] if the the performance goes bad, you have a way of visualizing in your head what’s going on. […]. It’s incredibly valuable to just have a bit of a mental model and not just treat it as a black box.

Para isso, eu gosto de assistir apresentações como essa, normalmente descritas como deep dive ou internals. Infelizmente, é um pouco difícil achar conteúdo que esteja nesse meio do caminho entre teoria pura e apenas a aplicação prática.

Esse tipo de conhecimento, além de ser mais perene, facilita transitar entre diferentes implementações do mesmo conceito. Por exemplo, basta ler a documentação do DuckDB para ter uma noção de como ele pode te ajudar a substituir rotinas Spark, mas dificilmente será útil em processos transacionais.

Esse último ponto emenda com outro tópico que eu queria discutir, repensar o valor que damos ao conhecimento especializado em ferramentas. É relevante para ter velocidade no desenvolvimento e maior confiança, mas vejo que as vezes ficamos muito presos ao que já conhecemos.

Ferramentas importam, mas não tanto

Quando se aprende a programar, é normal o discurso de que o importante é aprender lógica, a linguagem é uma questão secundária. Mas isso é verdade até os primeiros meses, depois escolher a “sua” linguagem vira algo extremamente importante na carreira do programador.

O mercado é avesso a migração de linguagens, é muito difícil trocar de “stack” tecnológica. Mesmo com 15 anos de experiência, seria difícil eu conseguir uma vaga de senior para uma linguagem que eu não tenha experiência prévia, especialmente se tiver uma vasta oferta de profissionais experientes como C# ou PHP por exemplo.

Os cientistas de dados têm especialidades também – pessoas que trabalham mais com dados não-estruturados, outras focadas em métodos estatísticos, ou especialistas em otimização – mas sinto que as barreiras são menores para migrar entre especialidades. É mais importante que você tenha mostrado capacidade de se aprofundadar em algo, do que ter experiência prévia em um domínio específico.

Meu mestrado é completamente irrelevante como pesquisa hoje em dia, mas ainda é importante como experiência. Não importa tanto o assunto da sua pesquisa, mas a premissa de que você conseguiu se aprofundar em um tópico relacionado, então pode fazer o mesmo em outro domínio próximo. Afinal, é uma área em que as inovações acadêmicas chegam muito rapidamente ao mercado, acompanhar essa evolução é primordial.

Apesar do mercado não incentivar, tento aproveitar as oportunidades que tenho para trabalhar com outras linguagens e tecnologias. É normal não ter a mesma velocidade no começo, mas concordo com essa sugestão do Norvig, que é importante aprender várias linguagens com propostas diferentes:

Learn at least a half dozen programming languages. Include one language that emphasizes class abstractions (like Java or C++), one that emphasizes functional abstraction (like Lisp or ML or Haskell), one that supports syntactic abstraction (like Lisp), one that supports declarative specifications (like Prolog or C++ templates), and one that emphasizes parallelism (like Clojure or Go).

Recentemente, eu precisei desenvolver uma aplicação C#, mas nunca tinha mexido em nada do ecossistema .NET. Após algumas semanas, eu já estava conseguindo ser produtivo, existem mais similaridades que diferenças entre linguagens como Java e C#. A infinidade de recursos que existe para aprendizado hoje em dia – IDEs/LSPs, IAs, documentação, Stack Overflow – facilitam muito essa migração para alguém com experiência prévia em outra linguagem.

Eu tenho minhas preferências, mas se o projeto é uma aplicação web tradicional, a linguagem dificilmente é uma questão. Normalmente, são outras decisões de arquitetura que viram um problema, como um banco de dados inadequado ou separação incorreta de serviços. Um argumento plausível – mas incompreendido e mal utilizado – em que a linguagem escolhida importa, são problemas de escalabilidade.

Seja criterioso com métricas

Um conhecimento muito cobrado dos cientistas de dados, é o domínio sobre métricas de avaliação. Saber escolher a mais adequada para o problema, como interpretá-las e suas limitações. O mesmo deveria ser cobrado de programadores e arquitetos, quando usam a performance como argumento de suas escolhas.

O erro mais comum que eu vejo ser cometido, é não entender a relevância da métrica. Por exemplo, se formos considerar uma taxa de falso positivo. Em um julgamento, condenar alguém inocente a pena de morte é um erro irreversível. Uma compra classificada erroneamente como fraude, é um pequeno transtorno em comparação. O problema e o contexto que dão a relevância de uma métrica.

O relatório das linguagens mais sustentáveis apareceu várias vezes no meu LinkedIn, destacando a ineficiência do Python: é tão lenta, que consome 70x mais energia para fazer o mesmo trabalho que C. É um resultado válido pelos experimentos feitos, mas que não é relevante para os cenário de uso mais comuns da linguagem.

Os testes foram feitos com tarefas chamadas CPU bound, como cálculo de autovalor e manipulação de árvores binárias. Para cenários de computação pesada, a “regra” é usar bibliotecas como o numpy, implementadas em outras linguagens mais rápidas. Para desenvolvimento de aplicações web, normalmente estamos falando de um cenário IO Bound, com muito mais tempo gasto com rede e armazenamento.

Mesmo quando uma métrica é relevante, ela pode ser muito limitada para representar todas as nuances do problema. Por exemplo, eu fiz essa comparação de performance entre gRPC e REST, utilizando diferentes linguagens de programação. Pelo primeiro experimento, considerando o tempo médio de resposta, poderia dizer que Python com gRPC é a melhor alternativa.

A média é uma métrica muito sensível a outliers, o que a torna pouco adequada para comparar resultados que envolvem comunicação por rede. É normal terem muitos outiliers em um experimento como esse, porque os protocolos de rede são otimizados para aumentar throughput em detrimento à constância.

Mudando o cenário do experimento, para requisições concorrentes, os resultados de Go com gRPC são melhores que Pyhton com gRPC:

Esses experimentos e resultados são mais relevantes para avaliar aplicações web, Python é uma alternativa competitiva e não 70x mais lento. Entretanto, pela natureza do problema, não é recomendado extrapolar esses resultados para outros cenários:

• os testes foram feitos em uma rede Wi-Fi, completamente diferente de uma comunicação entre servidores em um datacenter por exemplo;

• se eu tivesse resumido os resultados na média – eu poderia concluir que Python com gRPC é a solução mais rápida – o que seria uma conclusão válida e rasa ao mesmo tempo;

• o tempo é dominado por I/O, ter repostas em tempo parecido não significa que teremos a mesma escalabilidade, precisaríamos focar no consumo de recursos para comparar as linguagens nesse aspecto.

Eu deliberadamente não calculei as métricas, porque é natural que as pessoas simplesmente comparem os números e ignore as nuances. Números sempre trazem uma maior credibilidade e sensação de confiança, mesmo que não seja o caso .

Pior que lidar com as métricas de performance de software, é lidar com as métricas de produtividade e qualidade no desenvolvimento: quantidade de deploys, contagem de bugs, cobertura de testes, linhas de código, commits, “tamanho” de histórias, etc…

Eu compadeço da dor que os gestores sentem, fazer software é caro e caótico. Essas são as métricas possíveis de medir, mesmo que sejam pouco relevantes e pouco representativas. Isso é um reflexo de como a engenharia de software sofre de inveja da física, aceitar nossas limitações pode ajudar a reduzir as frustrações no processo de desenvolvimento de software.

Navalha de Ockham

Eu escrevi sobre o livro Código Limpo, discutindo como a visão positivista sobre o tema, fez dele um sucesso no lançamento e alvo de críticas recentes. As ideias propostas são muito boas, mas o tom prescritivo e científico do texto, não está realmente embasado com dados e rigor metodológico.

Como enxergo a engenharia de software mais próximo às ciências humanas que exatas, optei por tratar a engenharia de software com outra ferramenta do pensamento científico, a navalha de Ockham: em igualdade de condições, a explicação mais simples é geralmente a mais provável.

A ideia da navalha de Ockam é para comparar hipóteses científicas, a mais simples é melhor que a mais complexa. Os cientistas de dados tratam modelos por essa mesma heurística: modelos complexos são mais suscetíveis a problemas e via de regra são menos interpretáveis, o mais simples possível é a melhor opção.

No contexto de desenvolvimento, eu uso essa abordagem para definir arquitetura e aplicar metodologias. Infelizmente, é muito díficil definir o que é “funcionar” nesses contextos, mas procuro pensar sempre na alternativa mais minimalista e expandir quando sentir necessidade.

É normal arquitetura seguir pelo caminho inverso: ser desenhada para ser o mais “future proof” possível e acabar com várias soluções para problemas que nunca existirão. Um exemplo clássico desse cenário, são startups iniciando com arquitetura de microsserviços, perdendo velocidade para resolver um problema que só existe em grandes empresas.

Não existe uma regra para definir o quanto de “future proof” devemos ser, mas é possível iniciar a partir do mínimo para funcionar e adicionar complexidade após uma análise de custo/beneício: talvez eu não precise começar o projeto com Kubernetes, mas criar imagens Docker é algo simples que pode facilitar no futuro e traz benefícios imediatos.

As metodologias de trabalho seguem uma tendência parecida, em que as pessoas tentam emular os rituais de empresas bem sucedidas, na mesma lógica de seguir rotinas matinais de personalidades. É muito tentador creditar uma série de processos e regras como a razão do sucesso, porque basta aplicar a fórmula do sucesso para avançar.

Seguindo as ideias do manifesto ágil, sou a favor de implementar o mínimo de cerimônias e processos. Falando de scrum, começo com três cerimônias: refinamento, planning (sem poker) e daily. Para times menores e mais experientes, normalmente funciona muito bem. Outras cerimônias como demo e retrospectiva, aplico quando o time sente que faz sentido.

Seguir essa premissa “minimalista” não é a prova de falhas, não sei nem dizer se realmente é melhor. Mas entre pecar pela falta ou pelo excesso, minha impressão é que o excesso é o mais comum, porque existe toda uma dinâmicas de incentivos para vender e consumir soluções e metodologias complexas. Afinal, ninguém é demitido por comprar IBM.

Em uma entrevista recente com o autor – quando perguntado sobre dicas para um aspirante a engenheiros de dados – concordei plenamente com esse conselho:

Learn just enough abot the internals of the tools you are using, so that you have a reasonable mental model of what’s going on there. You don’t need to be able to, like, modify of the Kafka yourself, but I think having just enough of an idea of the internals that […] if the the performance goes bad, you have a way of visualizing in your head what’s going on. […]. It’s incredibly valuable to just have a bit of a mental model and not just treat it as a black box.

Uma das primeiras vezes, que entendi o valor de construir esses modelo mentais, foi quando aprendi sobre índices de banco de dados. Passei a entender melhor o plano de execução, quando a criação de um índice fazia sentido e otimizei consultas que outras pessoas não estavam conseguindo.

A solução mais comum para índices são as árvores B, esse tipo de estrutura é utilizada por diversos tipos de banco de dados: desde o SQLite, passando pelo Oracle Database e até mesmo em soluções distribuídas como o Dynamo DB.

Sendo uma estrutura tão prevalente em soluções de dados, acho importante que todo engenheiro de dados tenha uma noção de como ela funciona, construir esse modelo mental que Kleppmann comentou. Como eu queria brincar um pouco com a linguagem Rust, achei que era um bom exercício implementar uma árvore B na linguagem e escrever um pouco sobre.

O que é uma árvore B?

As árvores B são uma generalização das árvores binárias: ao invés de ter uma chave por nó, são \(k\) chaves por nós. Ela foi criada na década de 70 para lidar com dados persistentes, em um época em que a memória era escassa e a forma mais comum de armazenamento durável era o disco rígido. Atualmente, temos fartura de memória e armazenamento em SSD, novas estruturas como as LSM Trees foram desenvolvidas pensando nessa nova realidade.

Em soluções focadas em performance e escalabilidade, como o Cassandra por exemplo, faz muito sentido usar estruturas como as LSM Tree. Entretanto, algo que eu aprendi após anos trabalhando com “Big Data”: soluções com uso intensivo de memória têm performance excepcional, mas podem ficar inutilizáveis em cenários de escassez da mesma.

Apesar de ser uma estrutura com mais de 50 anos, desenvolvida em um cenário diferente do atual, segue sendo popular em novas soluções de dados por vários motivos:

• as ávores B não geram pressão em memória;
• são flexíveis como uma árvore binária (e.g. possibilidade de chaves parcias; suporte a múltiplos operadores de busca(\(>\), \(<\) e \(=\));
• dado é armazenado de forma ordenada;
• desempenho suficiente para muitos casos de uso.

Não faz muito sentido eu fazer (mais) uma explicação detalhada de como elas funcionam, porque existem infinitos materias sobre o assunto nos mais diversos formatos: aulas online, vídeos do Akita, blog posts e livros de algoritmos. É mais importante que o leitor procure esses materiais para entender sobre a estrutura, do que se preocupar em ler o restante desse post: eu fiz para meu próprio entretenimento, não como algo útil ou didático necessariamente.

Para fazer a implementação em Rust, revi o assunto no famoso “Cormen” e fiz praticamente uma cópia do proposto no livro. Implementei apenas a parte de inserção e busca, usando a estrutura para indexar arquivos no formato csv.

A estrutura da estrutura

Ao implementar uma estrutura de dados, normalmente começo imaginando as sub-estruturas que vou precisar e só depois penso na manipulação. Para essa implementação da árvore B, utilizei três sub-estruturas: BTree, Node e Key.

BTree

A BTree é a estrutura pública, que será utilizada pelas outras aplicações, contendo três campos:

• root é o nó raíz por onde serão iniciadas as buscas;
• order indica a quantidade de nós máximos que uma árvore pode conter;
• path é o diretório em que os arquivos da árvore serão armazenados.

pub struct BTree {
    root: Node,
    order: usize,
    path: String,
}

Node

O Node é a estrutura mais importante, que armazena e organiza as chaves de forma que as buscas possam ser feita em \(log(N)\). É composta pelos seguintes campos:

• key é um vetor contendo as chaves ordenadas;
• children é um vetor contendo os filhos de cada chave;
• leaf indica se o nó é uma folha, informação importante para tratar casos especiais de inclusão;
• filename é o nome do arquivo em que esse nó é armazenado.

pub struct Node {
    pub keys: Vec<Key>,
    pub children: Vec<String>,
    pub leaf: bool,
    pub filename: String,
}

Key

A estrutura Key é a mais simples, contendo apenas dois campos:

• value é o valor da chave propriamente dito, optei por deixar como String por simplicidade de implementação. Em uma solução produtiva, seria interessante ter algo mais flexível como um vetor de bytes ou um campo com tipo genérico.

• position é uma tupla com a posição da chave dentro do arquivo csv, o primeiro campo é o offset no arquivo e a segunda é a quantidade de bytes para ser lido a partir do offset.

pub struct Key {
    pub value: String,
    pub position: (u64, u64),
}

Criando a árvore

A busca em árvore costuma ser algo simples, a complexidade é maior para criação e manutenção da mesma. Optei por fazer apenas a inserção, que é o mínimo necessário para criar uma árvore funcional.

A inclusão na árvore é feito pela função insert, associada ao objeto Btree. A lógica de inclusão é feita pelo objeto Node, mas antes existe um desvio para o cenário em que o nó raiz está cheio.

pub fn is_full(&self, order: usize) -> bool {
    self.keys.len() == 2 * order - 1
}

pub fn insert(&mut self, key: Key) {
    if self.root.is_full(self.order) {
        let mut new_root = Node::empty(self.order, false, &self.path);
        new_root.children.push(self.root.clone().filename);
        new_root.split(0, self.order, &self.path);
        self.root = new_root;
    }

    self.root.insert(key, self.order, &self.path);
    self.save();
}

Se o nó da raiz estiver cheio, um nó vazio é criado e a raiz vira filho desse novo nó. Após tratar esse caso específico, a inserção do registro é feito pela função insert na estrutura Node:

fn find_position(&self, key: &Key) -> usize {
    let mut idx = 0;

    for (i, iter_key) in self.keys.iter().enumerate() {
        idx = i;
        if iter_key.value > key.value {
            break;
        }
    }

    if idx + 1 == self.keys.len() {
        if key.value > self.keys[idx].value {
            idx += 1;
        }
    }

    idx
}

fn add_key(&mut self, idx: usize, key: Key) {
    if self.keys.len() == 0 {
        self.keys.push(key);
    } else {
        self.keys.insert(idx, key);
    }
    self.save();
}

pub fn insert(&mut self, key: Key, order: usize, path: &str) {
    if self.leaf {
        self.add_key(self.find_position(&key), key.clone());
    } else {
        let mut idx = self.find_position(&key);

        if Node::load(&self.children[idx]).is_full(order) {
            self.split(idx, order, path);
            idx = self.find_position(&key);
        }

        Node::load(&self.children[idx]).insert(key, order, path);
    }
}

A função add_key assume que o nó tem espaço e não precisa ser separado em múltiplos. Se for um nó folha, essa função é chamada diretamente na posição definida por find_position. Caso contrário, o nó filho em que a chave será inserida é procurada pela mesma função find_position, esse nó filho é separado em dois caso esteja cheio.

Para separar um nó, a chave central do nó é usada como referência. No caso abaixo, a chave S vai para o nó superior, os filhos à esquerda permanecem no nó original e os filhos à direita são movidos para um novo nó.

A função split faz esse processo de rotação das chaves, que é realizado antes da inclusão em um nó cheio:

pub fn split(&mut self, pivot: usize, order: usize, path: &str) {
    let left = &mut Node::load(&self.children[pivot]);
    let key = left.keys[order - 1].clone();

    let right = Node {
        keys: left.keys[order..left.keys.len()].to_owned(),
        children: match left.leaf {
            true => Vec::with_capacity(2 * order),
            false => left.children[order..left.children.len()].to_owned(),
        },
        leaf: left.leaf,
        filename: Node::filename(path),
    };

    right.save();

    left.keys.resize(order - 1, Key::create("", (0, 0)));

    if !left.leaf {
        left.children.resize(order, String::from(""));
    }

    left.save();

    self.keys.insert(pivot, key);
    self.children.insert(pivot + 1, right.filename);

    self.save()
}

Em várias momentos, as estruturas são persistidas e lidas do armazenamento, usando as funções savee load respectivamente. Essas funções serializam e desserializam o objeto Node no formato json, usando a biblioteca serde_json.

pub fn save(&self) {
    let mut file = File::create(&self.filename).unwrap();
    file.write_all(serde_json::to_string(self).unwrap().as_bytes())
        .unwrap();
}

pub fn load(filename: &str) -> Node {
    serde_json::from_slice(&fs::read(filename).unwrap()).unwrap()
}

Cada nó é salvo em um arquivo com nome aleatório, gerado pela função filename:

fn filename(path: &str) -> String {
    format!("{}/{}.json", path, Uuid::new_v4().to_string())
}

O formato json não é o ideal em termos de performance, mas é legível por humanos e prático para ser utilizado em um código para estudos. Abaixo, um exemplo de nó salvo em disco, gerado pelos testes unitários:

{
    "keys": [
        {
            "value": "9b35db6e-49d9-4d91-b5f6-973b8a9111f4",
            "position": [
                0,
                0
            ]
        },
        {
            "value": "d47fbd93-cb1a-4e01-82b2-4325aa8cb1a3",
            "position": [
                0,
                0
            ]
        }
    ],
    "children": [
        "btree_test_search/d1740cf9-8fa9-471d-9ba6-99ff1462f5c6.json",
        "btree_test_search/9ba9bd01-6b3e-4441-a70b-253c86424cd3.json",
        "btree_test_search/7248b1e6-88f6-4f8e-a07b-0952347adc47.json"
    ],
    "leaf": false,
    "filename": "btree_test_search/1c3df73f-f321-4b3a-a545-9917ad2ecb4e.json"
}

Buscando na árvore

A busca é feito de forma recursiva, como é comum em estruturas de árvore. A função pública search da Btree tem apenas o parâmetro value com o valor da chave a ser procurado, a função search_tree é a que de fato realiza a busca recursiva.

fn search_tree(node: &Node, value: String) -> Option<Key> {
    for (i, key) in node.keys.iter().enumerate() {
        if key.value == value {
            return Some(key.clone());
        } else if key.value > value {
            if node.leaf {
                return None;
            } else {
                return BTree::search_tree(&Node::load(&node.children[i]), value);
            }
        }
    }

    if node.leaf {
        None
    } else {
        BTree::search_tree(&Node::load(&node.children[node.keys.len()]), value)
    }
}

pub fn search(&self, value: &str) -> Option<Key> {
    BTree::search_tree(&self.root, value.to_string())
}

Com a busca e a inserção criadas, já temos o mínimo para fazer o indexador.

Indexando os CSVs

Os arquivos CSVs são muito utilizados para lidar com dados tabulares. A organização física desses arquivos é parecida com a de uma tabela em um banco relacional, sendo orientado a linhas e com marcadores utilizados para indetificar início e fim dos campos e registros.

A função index_file recebe um arquivo e uma árvore, itera linha-a-linha no arquivo e armazena três informações na árvore: o valor da chave, a posição da linha no arquivo e a quantidade de bytes por linha.

pub fn index_file(file: &File, tree: &mut BTree) {
    let mut reader = BufReader::new(file);

    let mut buf = String::new();
    let mut offset: u64 = 0;

    loop {
        buf.clear();

        let size: u64 = reader
            .read_line(&mut buf)
            .expect("reading from cursor shouldn't fail")
            .try_into()
            .unwrap();

        if size == 0 {
            break;
        }

        let key_value = match get_key(0, &buf) {
            None => {
                offset += size;
                continue;
            }
            Some(value) => value,
        };

        tree.insert(Key::create(key_value, (offset, size)));
        offset += size;
    }
}

Para recuperar as informações do arquivo, a função recebe o arquivo e uma tupla contendo a posição da linha e seu tamanho.

pub fn read_line(file: &mut File, position: (u64, u64)) -> Result<String, Box<dyn error::Error>> {
    let (start, offset) = position;
    file.seek(SeekFrom::Start(start))?;

    let mut read_buf = vec![0; offset.try_into().unwrap()];
    file.read_exact(&mut read_buf)?;

    match String::from_utf8(read_buf) {
        Err(e) => Err(Box::new(e)),
        Ok(line) => Ok(line),
    }
}

E a performance?

Para testar o indexador, gerei um arquivo CSVs com 10.000.000 de registros e aproximadamente 500MB de tamanho. Abaixo, o script para indexar esse arquivo usando nós de ordem 1.000:

fn main() -> std::io::Result<()> {

    let filename = "/home/gdarruda/Projects/sandbox/clients.csv";
    let mut file = File::open(filename)?;
    let mut tree = index::btree::BTree::create(1000, "/home/gdarruda/btree_files");
    csv::index_file(&file, &mut tree);

    Ok(())
}

Para indexar esse arquivo, foram necessárias 3:17 horas, mas não passou de 3MB de consumo total de memória. Um tempo alto para indexar, teríamos várias oportunidades de otimização – melhorar serialização; não forçar escrita em disco para cada inclusão; otimizar os tamanhos dos nós; usar cache – mas esse não é o ponto do exercício proposto.

Olhando para o desempenho da busca – considerando o pior caso, que é procurar e não encontrar um registro – procurando por 1.000 chaves aleatórias não existentes, o tempo médio de busca foi de 474µs com desvio de 26µs.

fn main() -> std::io::Result<()> {

    let filename = "/home/gdarruda/Projects/sandbox/clients.csv";
    let mut file = File::open(filename)?;
    let tree = index::btree::BTree::load("/home/gdarruda/btree_files");

    for uuid in (0..1000).map(|_| Uuid::new_v4().to_string()) {

        let now = SystemTime::now();

        match tree.search(&uuid) {
            None => {},
            Some(key) => {
                match csv::read_line(&mut file, key.position) {
                    Err(e) => {println!("Error: {}", e)},
                    Ok(line) => {println!("Found line: {}", line)}
                }
            }
        };

        match now.elapsed() {
            Ok(elapsed) => {
                println!("{}", elapsed.as_micros());
            }
            Err(e) => {
                println!("Error: {e:?}");
            }
        }

    }

    Ok(())
}

Pode-se pensar em otimizações para essa parte da busca também, mas essa implementação simplória já demonstra a utilidade de uma estrutura como essa para grandes base de dados: boa performance de busca, baixíssimo consumo de memória.

Por que fazer isso?

Não sou a favor que os programadores fiquem recriando banco de dados e frameworks: apesar de ser uma ótima forma de aprender profundamente sobre um tema, provavelmente não é a forma mais eficiente. De qualquer forma, acho fundamental ter uma noção intuitiva de como as coisas funcionam e não focar apenas nas APIs das ferramentas.

Mais importante que entender os detalhes da minha implementação, eu gostaria que os programadores conseguissem responder perguntas sobre índices basedos em árvore:

• Se vou ler 50% da tabela, um índice me ajuda? E se for 75%? E se for 5%?
• Índices fazem sentido para armazenamento colunar, como um arquivo parquet por exemplo?
• Quais as vantagens e desvantagens de colocar múltiplas colunas em um único índice?
• Em uma coluna com poucos valores distintos, faz mais sentido usar ela como partição ou criar um índice? Por quê?

Obviamente, todas essas perguntas têm vários “depende” em uma situação real, mas é possível ter uma noção das respostas pelo conhecimento teórico. São perguntas que realmente aparecem no dia-a-dia, escolher a melhor solução de armazenamento costumar ser uma porta de sentido único.

Quando eu comecei a carreira, o padrão era usar bancos relacionais, no máximo a discussão era qual deles escolher. Hoje em dia, pode-se recorrer a uma miríade de soluções especializadas para cada caso de uso: desde armazenar dados como arquivos em storage, passando por bancos relacionais e diversos tipos de bancos NoSQL especializados (e.g. grafos, chave-valor, documento, MPP).

As soluções especializadas podem ser mais escaláveis e nem sempre usar Postgres para tudo é a melhor opção, mas ferramentas especializadas podem ser inutilizáveis quando adaptadas para cenários fora de seu caso de uso. Aprender sobre todas as soluções de todos provedores de cloud é inviável, focar em conhecer os conceitos das ferramentas é melhor que ler infinitos artigos no Medium comparando as soluções em termos de “prós e contras”.

Há várias camadas de abstração – para que o desenvolvedor posso pensar em seus algoritmos como uma sequência de passos – mas na prática muita coisa é executada fora de ordem. Nem mesmo o processador seguem a ordem das instruções, execução out of order é implementado em todas arquiteturas modernas para evitar desperdício de ciclos.

Essas abstrações funcionam muito bem em certos cenários, como é o caso de servidores web e sistemas de banco de dados por exemplo. Entretanto, algumas vezes é necessário lidar diretamente com concorrência e paralelismo.

Não é fácil trabalhar com esses conceitos – é uma mudança fundamental no modelo mental do programador – não surpreende que seja um tópico intimidador para muita gente. Minha ideia é escrever esse post tentando explicar de forma didática, como fazer esse tipo de aplicação em Python.

Conceitos básicos

O que complica (ainda mais) lidar com de problemas de concorrência e paralelismo, é a abundância de conceitos e detalhes de implementação de cada linguagem. Por isso, é bom alinhar alguns conceitos, antes de entrar na implementação.

A ideia é realmente definir o mínimo, tudo bem se a explicação resumida não fizer completo sentido, não acho que seja impeditivo para o entendimento das implementações.

Processos

No contexto de sistemas operacionais, um processo é uma instância do programa sendo executado. Pontos importante sobre processos:

• os processos têm memória isolada, o que está na memória de um processo não pode ser visto por outro;
• o sistema operacional é responsável por escalonar os processos, alternando a execução para que todos tenham algum tempo de execução de acordo com a sua prioridade;
• um processo em execução pode ser interrompido por I/O, entrando em espera quando precisa interagir com algo externo (e.g. rede, armazenamento);
• existe um custo para alternar entre diferentes processos no processador, como limpar os registradores e mudar de pilha.

Threads (kernel threads)

Um processo pode conter uma ou múltiplas threads, são conceitos parecidos, mas com diferenças importantes:

• threads de um mesmo processo podem compartilhar recursos entre si, como conexões de rede e dados na memória;
• o custo de alternar entre threads do mesmo processo é mais baixo que alternar entre diferentes processos;
• dependendo do sistema operacional, o custo de criar e destruir threads é muito mais baixo que processos.

Co-rotinas e tarefas

Os processos e threads são conceitos a nível do sistema operacional, mas é comum as linguagens implementaram algo similar e mais enxuto no próprio runtime. O Python tem as co-rotinas e tarefas, são mais leves para criar/destruir que threads e executadas de forma cooperativa ao invés de preemptiva.

As implementações diferem entre linguagens, as ideias e estratégias discutidas nesse post não se aplicam as co-rotinas de outras linguagens necessariamente.

GIL (Global Interpreter Lock)

A implementação padrão do Python usa o GIL (Global Interpreter Lock), que não permite a execução paralela de threads de um mesmo processo. A presença do GIL simplifica o desenvolvimento da linguagem, mas impede o paralelismo de processamento a nível de thread.

A proposta de deixar o GIL opcional foi aceita, será possível desabilita-ló no Python 3.13. É necessário esperar para ver como será a migração do ecossistema, mas imagino que as limitações de paralelismo serão realidade por muito tempo ainda.

Paralelismo de dados

Raramente é simples transformar um problema sequencial em paralelizável, muitas vezes é simplesmente impossível. Uma estratégia alternativa é aplicar o paralelismo de dados, que consiste em dividir a entrada e combinar os resultados posteriormente.

Um candidato ideal para essa estratégia, é o script que utilizei em outro post para gerar uma massa de dados aleatória, simulando a saída de um modelo de machine learning. Abaixo, a função que gera uma base de amostra:

def generate(self, num_rows: int) -> pd.DataFrame:

    df = pd.DataFrame(
        {
            **{"id_client": [str(uuid.uuid4()) for _ in range(num_rows)]},
            **{f"class_{c}": np.random.uniform(size=num_rows)
               for c in range(self.num_classes)}
        }
    )

    df.to_parquet(f"{self.path}/{num_rows}-{uuid.uuid4()}.parquet")

A estratégia mais simples para paralelizar esse processo, é executar essa função múltiplas vezes de forma independente: podemos executar a função para gerar \(n\) amostras ou executar \(k\) vezes gerando \(n/k\) amostras por execução, é o mesmo resultado em termos de funcionalidade.

Um dos jeitos mais simples de aplicar paralelismo de dados, é utilizando a ideia de piscina de threads. A “piscina” é um conjunto fixo de threads que ficam disponíveis para uso, as tarefas são enfileiradas e entram em processamento quando uma thread fica disponível. Abaixo, uma ilustração dessa estratégia:

Para implementá-la, é necessário separar o problemas em pedaços menores, o que é trivial nesse caso. Basta dividir o total de linhas pelo tamanho desejado para cada batch:

def _build_batches(self, num_rows) -> Iterable[int]:

    for _ in range(num_rows//self.batch_size):
        yield self.batch_size
    
    remainder = num_rows % self.batch_size

    if remainder > 0:
        yield remainder

O tamanho do batch não é muito importante, exceto pelo consumo de memória. Cada chamada da função gera um DataFrame com o tamanho do batch, é necessário ter memória suficiente para que todas as threads possam manter o DataFrame em memória simultaneamente.

Com os batches criados – usando a função map de um ThreadPool – generate é chamada para cada item de batches:

def generate_parallel(self,
                      num_rows: int) -> pd.DataFrame:

    batches = self._build_batches(num_rows)

    with ThreadPool(os.cpu_count()) as p:
        p.map(self.generate, batches)

Essa implementação está tecnicamente correta, mas não faz sentido devido ao GIL. No final, generate_parallel é mais lenta que generate, ja que as threads não podem ser executadas paralelamente e ainda é necessário coordená-las:

NUM_ROWS = 1_000_000
BATCH_SIZE = 5_000
NUM_CLASSES = 10

generator = SampleGenerator(BATCH_SIZE, NUM_CLASSES, "samples")
%timeit generator.generate_parallel(NUM_ROWS)
%timeit generator.generate(NUM_ROWS)

# 4.8 s ± 51.6 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
# 3.73 s ± 16.9 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)

A solução para esse caso, é simplesmente trocar o tipo de pool, usando processos ao invés de threads. O código é idêntico, bastando alterar o tipo de contexto utilizado, de ThreadPool para Pool:

def generate_parallel(self,
                      num_rows: int) -> pd.DataFrame:

    batches = self._build_batches(num_rows)

    with Pool(os.cpu_count()) as p:
        p.map(self.generate, batches)

Usando um processador de 6 núcleos com SMT, criar as amostras é ~ 4,29 vezes mais rápido, trazendo o aumento de desempenho esperado:

NUM_ROWS = 1_000_000
BATCH_SIZE = 5_000
NUM_CLASSES = 10

generator = SampleGenerator(BATCH_SIZE, NUM_CLASSES, "samples")
%timeit generator.generate_parallel(NUM_ROWS)
%timeit generator.generate(NUM_ROWS)

# 873 ms ± 2.23 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
# 3.75 s ± 25.6 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)

Algumas perguntas surgem com esses resultados. Se é tão simples, usar processos ao invés de threads, por que usar threads? Para que servem as threads, se existe o GIL?

O problema proposto tem características que o tornam perfeitos para ser utilizado em múltiplos processos:

• pode ser separado e combinado a custo zero, a função recebe apenas um inteiro de entrada e não precisa se comunicar com os demais processos;

• é um processo que demanda muito processamento e pouca movimentação dados, o GIL anula a utilidade de trabalhar com múltiplas threads.

Nem sempre é o caso, existem cenários em que threads podem ser úteis, como é o caso dos cenários de aplicação descritas como I/O bound.

O cenário “I/O bound”

Muitos problemas do dia-a-dia não são limitados por tempo de processamento, mas por movimentação de dados fora da memória: escrita em banco de dados, comunicação por rede, escrita em storage, postagem em filas, etc. Essas operações são ordens de grandeza mais lentas que o acesso a memória, são nesses cenários que o uso de threads e co-rotinas fazem sentido.

Para ilustrar esse cenário, o problema proposta agora é salvar essas amostras aleatórias em uma tabela no PostgreSQL. Para ter como baseline, as classes DatabaseNaive e LoaderNaive são a uma solução trivial para esse problema:

class DatabaseNaive(Database):

    def __init__(self,
                 connection_url: str,
                 num_classes: int) -> None:

        super().__init__(connection_url, num_classes)
        self.conn = psycopg.connect(connection_url)

    def save_message(self, prediction: dict):

        with self.conn.cursor() as cur:
            cur.execute(*self._build_insert(prediction))

        self.conn.commit()

class LoaderNaive():

    def __init__(self, db: DatabaseNaive) -> None:
        self.db = db

    def load(self, df: pd.DataFrame):

        for _, row in df.iterrows():
            self.db.save_message(row.to_dict())

A solução acima salva um registro de cada vez, esperando a escrita no banco de dados, antes de passar para o próximo. Para 100.000 registros, esse processo demora aproximadamente 6 minutos:

%%timeit

NUM_CLASSES = 10

db = DatabaseNaive(CONNECTION_URL, NUM_CLASSES)
db.create_table()

loader = LoaderNaive(db)
loader.load(predictions)

db.close()

# 5min 54s ± 6.42 s per loop (mean ± std. dev. of 7 runs, 1 loop each)

Threads sendo úteis

A estratégia de threads funciona nesse cenário, porque escrever em banco de dados depende muito de I/O, diferente de gerar amostras que é um processo que demanda muito tempo do processador.

Uma preocupação ao lidar com threads, é garantir que os objetos compartilhados sejam thread safety. Nesse caso, o objeto que precisa dessa garantia é a conexão de banco de dados, compartilhado entre as threads.

O conector de PostgreSQL para Python tem a opção de usar o ConnectionPool, que cria uma piscina de conexões disponíveis para serem alocadas. Dessa forma, cada thread pode utilizar uma conexão distinta, o que elimina os possíveis problemas de concorrência (e.g. condição de corrida, corrupção de dados). Para abstrair esse objeto, foi criada uma classe DatabasePool:

class DatabasePool(Database):

    def __init__(self,
                 connection_url: str,
                 num_classes: int,
                 num_threads: int) -> None:

        self.connection_url = connection_url
        self.num_classes = num_classes

        self.pool = ConnectionPool(connection_url,
                                   min_size=num_threads)

    def create_table(self):
        with self.pool.connection() as conn:
            self._create_table(conn)

    def save_message(self, prediction: dict):

        with self.pool.connection() as conn:
            with conn.cursor() as cur:
                cur.execute(*self._build_insert(prediction))
                conn.commit()

Estendendo a implementação LoaderNaive e adicionando a função load_parallel, é possível fazer a carga no banco de dados com múltiplas threads. A função load_parallel separa o DataFrame em pedaços, para serem posteriormente processados pelo método load:

class LoaderMultiThread(LoaderNaive):

    def __init__(self,
                 batch_size: int,
                 db: DatabasePool,
                 num_threads: int) -> None:

        self.db = db
        self.batch_size = batch_size
        self.num_threads = num_threads

    def load_parallel(self, df: pd.DataFrame):

        dfs = self._make_slices(df)

        with ThreadPool(self.num_threads) as p:
            p.map(self.load, dfs)

Diferentemente de gerar as amostras, nesse problema existe um ganho de desempenho com o uso de threads, o processo é executado em cerca de 1 minuto e 30 segundos ao invés de 6 minutos.

%%timeit

NUM_THREADS = 48
BATCH_SIZE = 1_000

db = DatabasePool(CONNECTION_URL, NUM_CLASSES, NUM_THREADS)
db.create_table()

loader = LoaderMultiThread(BATCH_SIZE, db, NUM_THREADS)
loader.load_parallel(predictions)

db.close()

# 1min 32s ± 14.4 s per loop (mean ± std. dev. of 7 runs, 1 loop each)

O ganho desse desempenho não veio do aumento de paralelismo, mas de possibilitar concorrência: quando uma thread precisa aguardar o retorno do banco de dados e fica bloqueada, o sistema operacional alterna para executar outra thread.

Por que usei 48 threads? É difícil estimar esse número porque tem muitas variáveis: performance do banco de dados, latência de rede, operações concorrentes, etc. A estratégia foi experimentar diversos valores, portanto esse valor só vale para esse cenário.

Apesar de ser efetivo usar threads, essa estratégia faz mais sentido quando não é possível usar co-rotinas e tarefas. Usar interrupções para escalonar as threads talvez não seja o melhor cenário, além de envolver decisões complicadas como escolher o número ideal de threads.

Co-rotinas: mais simples e rápido

O pyscopg implementa comunicação assíncrona com asyncio, que é um jeito mais elegante e nativo de resolver o problema da concorrência. O asyncio tem vários conceitos como tarefas, corotinas, etc – eu mesmo tenho uma compreensão superficial – então recomendo a documentação e outros materiais, caso o leitor queira entender melhor o que está sendo feito.

Para esse cenário, tentei manter a interface de uso o mais parecido possível com a versão síncrona, mas usando a implementação assíncrona do psycopg:

class DatabaseAsync(Database):

    def __init__(self,
                 connection_url: str,
                 num_classes: int) -> None:

        self.connection_url = connection_url
        self.num_classes = num_classes

    def create_table(self):
        conn = psycopg.connect(self.connection_url)
        self._create_table(conn)
        conn.close()

    async def get_conn(self):
        return await psycopg.AsyncConnection.connect(self.connection_url)

    async def save_message(self, conn, prediction: dict):
        async with conn.cursor() as cur:
            await cur.execute(*self._build_insert(prediction))

        await conn.commit()

    async def close(self):
        await self.get_conn().close()

O LoaderAsync é muito parecido com o LoaderNaive, processando todos os dados de uma vez ao invés de separá-los em batches menores. Ao invés de trabalhar com um número fixo de threads reaproveitáveis, uma tarefa é criada para cada amostra a ser inserida. As tarefas são baratas de criar e destruir, por isso é possível fazer essa implementação mais simples:

class LoaderAsync(LoaderNaive):

    def __init__(self,
                 db: DatabaseAsync) -> None:
        self.db = db

    async def load_async(self, df: pd.DataFrame):

        conn = await self.db.get_conn()

        async with conn:
            async with asyncio.TaskGroup() as tg:
                for _, row in df.iterrows():
                    tg.create_task(self.db.save_message(conn, row.to_dict()))

O TaskGroup oferece uma abstração similar ao ThreadPool, inicializando as tarefas e esperando o término de todas que foram criadas sob o contexto. Em termos de performance, foi ainda mais rápido que a solução multithread, com tempo de execução próximo de 25 segundos:

db = DatabaseAsync(CONNECTION_URL, NUM_CLASSES)
db.create_table()

loader = LoaderAsync(db)
await loader.load_async(predictions)

A solução continua sujeita ao GIL, os ganhos em relação ao multithread devem ser provenientes do escalonamento colaborativo, provavelmente mais efetivo para o problema. Entretanto, é bom ressaltar que boa parte do ecossistema Python não suporta asyncio, então nem sempre é possível optar por essa estratégia.

Apesar dos ganhos expressivos, estamos utilizando apenas um núcleo do processador. Separando o problema em vários processos – temos uma execução assíncrona menos eficiente, conforme observado nos testes – mas que pode tirar melhor proveito do hardware disponível.

Processos no lugar de Threads

No primeiro exemplo, substituir processos por threads foi uma questão de trocar o contexto de ThreadPool para Pool. Nesse caso, fazer essa mudança gera um erro pouco claro para o usuário:

db = DatabaseNaive(CONNECTION_URL, NUM_CLASSES)
loader = LoaderMultiProcess(BATCH_SIZE, NUM_THREADS, db)
loader.load_parallel(predictions)

db.close()

# TypeError: no default __reduce__ due to non-trivial __cinit__

É comum ter esses erros estranhos ao trabalhar com múltiplos processos, normalmente são devidos à serialização. Lembre-se que os processos têm memória isolada, para compartilhar objetos entre eles, pode ser necessário traduzir em um formato binário transportável. O problema é que muitos objetos não podem ser transformados, uma conexão de banco de dados tem conexões de rede abertas que não podem ser migradas entre processos distintos.

Para lidar com essa limitação, existe um “truque” que consiste em atrasar a criação do objeto complexo. Essa é a diferença da classe DatabaseLazy para DatabaseNaive, o construtor da DatabaseLazy não cria a conexão no construtor:

class DatabaseLazy(Database):

    def __init__(self,
                 connection_url: str,
                 num_classes: int) -> None:

        super().__init__(connection_url, num_classes)
        self.conn = None

    def _get_conn(self):

        if self.conn is None:
            self.conn = psycopg.connect(self.connection_url)

        return self.conn

    def create_table(self):
        self._create_table(self._get_conn())

    def save_message(self, prediction: dict):

        conn = self._get_conn()

        with self.conn.cursor() as cur:
            cur.execute(*self._build_insert(prediction))

        conn.commit()

    def close(self):
        self._get_conn().close()

A conexão só é criada na primeira chamada de _get_conn, antes disso é um objeto None. A cópia do objeto DatabaseLazy é feita antes dessa primeira chamada, na abertura do Pool:

class LoaderMultiProcess(LoaderNaive):

    def __init__(self,
                 batch_size: int,
                 num_threads: int,
                 db: DatabaseLazy) -> None:

        self.db = db
        self.batch_size = batch_size
        self.num_threads = num_threads

    def load_parallel(self, df: pd.DataFrame):

        dfs = self._make_slices(df)

        with Pool(self.num_threads) as p:
            p.map(self.load, dfs)

Usando LoaderMultiProcess temos o melhor tempo de execução, ficando abaixo de 10 segundos em média, estamos falando de uma solução ~41,11 vezes mais rápida que a solução inicial:

%%timeit
import os

db_temp = DatabaseNaive(CONNECTION_URL, NUM_CLASSES)
db_temp.create_table()
db_temp.close()

db = DatabaseLazy(CONNECTION_URL, NUM_CLASSES)
loader = LoaderMultiProcess(BATCH_SIZE, NUM_THREADS*(os.cpu_count()//2), db)
loader.load_parallel(predictions)

db.close()

# 8.61 s ± 13.9 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)

Faz sentido explorar essa abordagem quando há muitos núcleos disponíveis e os ganhos do paralelismo sobrepujam a eficiência das co-rotinas. Em outras linguagens, as tarefas normalmente podem ser processadas paralelamente, sem demandar esse trabalho extra.

Para quem tiver curiosidade, os códigos dos experimentos estão nesse repositório.

Alternativas e futuro

A maioria das linguagens foi criada sem pensar em concorrência e execução assíncrona, o que acaba em soluções não ideais para o problema. A presença do GIL no Python, adiciona mais camadas de complexidade para uma questão que já é inerentemente difícil em quase todos os ambientes de desenvolvimento.

A ideia de trabalhar com múltiplos processos é muito parecido com computação distribuída, o que faz o PySpark parecer uma alternativa interessante em um primeiro momento. Uso bastante e gosto quando a solução pode ser escrita em Spark SQL, mas não faz sentido usar exclusivamente para paralelizar código Python devido ao overhead de integração com a JVM.

O Dask parece ser a melhor alternativa, se a ideia é paralelizar código Python e até distribuí-lo. Não tenho experiência com o framework, mas ele ainda é uma abstração complexa para contornar algo que a maioria das linguagens suporta nativamente.

Dado esse cenário, fico ansioso para acompanhar como será a adoção do ecossistema para execução sem o GIL. Existem muitas iniciativas(1, 2 e 3) para acelerar o Python, mas a remoção do GIL depende de uma adoção pelos usuários, frameworks e bibliotecas para vingar.

Imagino que a maioria aceite que existe um grau de subjetividade no que tange qualidade de código. Não existe um “ideal platônico” de código, que pode ser criado sistematicamente seguindo uma série de passos. Mas o quanto a engenharia de software pode nos ajudar a reduzir essa subjetividade?

O positivismo da engenharia de software

As várias definições de engenharia de software, normalmente destacam seu caráter sistemático e científico, como a definição da IEEE por exemplo:

The systematic application of scientific and technological knowledge, methods, and experience to the design, implementation, testing, and documentation of software

Quando se discute as limitações da engenharia de software, normalmente é levado em conta o fato de ser uma nova área de conhecimento. Aos poucos, esse rol de métodos e conhecimentos da engenharia de software está sendo construído, os problemas atuais são uma questão de maturidade.

É uma perspectiva positivista da situação: seja pela ideia de seguir uma metodologia científica para construção do conhecimento real (positivo), seja pela perspectiva de estarmos nos primeiros passos de uma área complexa e específica na hierarquia de Comte.

Uma área próxima, que evoluiu de acordo com o positivismo, é o design de banco de dados. Existiam várias abordagens para o problema, mas o modelo de representação relacional se consolidou nos anos 70 e os conceitos se mantiveram até os dias de hoje. Surgiram alternativas aos bancos relacionais, mas o aspecto interessante é como dominamos o seu uso: os métodos são bem definidos, já vi modelos lógicos criados na década de 80 que eu desenharia da mesma forma hoje.

A minha percepção no início da carreira – fim dos anos 2000, início dos anos 2010 – era que a orientação a objetos seguiria o mesmo caminho do modelo relacional. Pode ter sido ser sido a ingenuidade de um iniciante, mas eu imaginava que existiria um análogo às regras de normalização para modelagem de classes.

Alguém lembra de UML? A ideia era que poderíamos ter uma documentação tão precisa, que alguém poderia traduzir em código em uma fábrica de software do outro lado do mundo. Uma solução temporária, porque logo mais seria possível gerar código automaticamente a partir de UML, alcançado o sonhado low-code que já discuti em outra oportunidade.

A orientação a objetos foi largamente adotada no desenvolvimento de sistemas e trouxe avanços, mas não se chegou a um método rigoroso e sistemático. Pode-se enxergar como um erro de percurso – que podemos evoluir a orientação a objetos, misturar com outros paradigmas, criar um completamente novo – ou entender que não existe um percurso.

É completamente razoável, a ideia de sistematizar uma área derivada da computação, mas talvez a parcela de computação do problema que queremos resolver seja muito pequena. A engenharia de software, não estaria sofrendo de inveja da física?

Software como processo criativo

O livro Clean Code era uma recomendação padrão sobre engenharia de software, mas nos últimos anos tem sido questionado [1, 2, 3], discussões sobre Uncle Bob e o livro tendem a ser acaloradas [1, 2, 3, 4, …].

Não quero discutir o mérito do livro em si – se ele ficou datado ou se nunca foi bom para início de conversa – mas pensar na forma que o consumimos. Seria um debate menos polêmico, se tratássemos desenvolvimento como um processo criativo, mais parecido com fotografia¹ que construção de pontes.

O Clean Code não deve ser lido como um guia de práticas, mas uma obra influente na época em que foi escrita. Ler como formação de repertório, para entender como as coisas eram feitas e como chegamos aqui, da mesma forma que tratamos os clássicos do cinema e literatura por exemplo.

No capítulo introdutório, Uncle Bob até faz uma analogia de programação com o processo criativo.

Considere esse livro como uma descrição da Escola de Código Limpo da Object Mentor. As técnicas e ensinamentos são a maneira pela qual praticamos nossa arte. Estamos dispostos a alegar que se você seguir esses ensinamentos, desfrutará de benefícios que também aproveitamos e aprenderá a escrever códigos limpos e profissionais. Mas não pense que estamos 100% “certos”. Provavelmente há outras escolas e mestres que têm tanto para oferecer quanto nós. O correto seria que você aprendesse com elas também.

Por outro lado, o restante do livro tem outro tom. São muitas afirmações assertivas e prescritivas de como as coisas devem ser, conclusões unilaterais sobre aspectos subjetivos. Um exemplo dessa postura, é essa afirmação sobre parâmetros das funções:

A quantidade ideal de parâmetros para uma função é zero (nulo). Depois vem um (mônade), seguido de dois (díade). Sempre que possível devem-se evitar três (tríade) parâmetros. Para mais de três (políade) deve ter um motivo muito especial – mesmo assim não devem ser usados.

É uma preferência do autor, mas escrita como um lema matemático. Uma opinião que está no contexto da linguagem Java de 2008: sem parâmetros com valor padrão, orientada a objetos e sem suporte a funções de alta ordem. A escrita reflete a visão positivista, apesar de não ser um conhecimento de caráter científico.

Pessoalmente, acho (bem) estranha essa aversão a parâmetros, mesmo para a época em que foi escrito o livro. Posso citar vários argumentos sobre o porquê discordo, mas é possível encerrar essa discussão? A proposição não é sustentada por um experimento ou algum outro tipo de evidência científica, mas meus argumentos contrários também não.

Mesmo que você também discorde dessa ideia, ainda é interessante conhecê-la. Dada a influência do livro, muitos códigos foram criados seguindo essa premissa e novos seguirão sendo criados, independente da opinião individual sobre o tema.

Seria melhor, se tratássemos esse tipo de afirmação mais como “regras” de composição da fotografia (e.g. regra dos terços, espaço negativo e linhas principais), do que como um método de engenharia.

A regra dos terços tem uma longa história, originando-se na escola pictorialista dos primórdios da fotografia. Voltou a tona com a popularização das câmeras fotográficas entre fotógrafos amadores – é uma regra objetiva e prática, assim como a questão de parâmetros – que a torna atraente para iniciantes. O reducionismo da regra já era era questionado na década de 50, pelo famoso fotógrafo Henri Catier-Bresson:

In applying the Golden Rule, the only pair of compasses at the photographer’s disposal is his own pair of eyes. Any geometrical analysis, any reducing of the picture to a schema, can be done only (because of its very nature) after the photograph has been taken, developed, and printed — and then it can be used only for a postmortem examination of the picture. I hope we will never see the day when photo shops sell little schema grills to clamp onto our viewfinders; and the Golden Rule will never be found etched on our ground glass.

Não existe uma ciência por trás das técnicas de composição, mas também não existe a ambição de ser algo científico. Sem essa pretensão, os debates ficam mais leves e não se espera uma aplicação sistemática sem reflexão. Um fotógrafo experiente conhece as “regras”, mas as quebra quando necessário.

O Clean Code é um conteúdo indiscutivelmente importante pela relevância – mas que deve ser consumido com parcimônia e olhar crítico – e nós programadores não estamos acostumados com isso.

Diferentes escolas

É uma situação complicada, quando sua opinião vai em direção oposta a alguém renomado. Quem sou eu para discordar do Uncle Bob, autor de vários livros influentes? Talvez, essa anedota do encontro do fotógrafo Willian Eggleston com o supracitado Henri Catier-Bresson, tenha algo a nos ensinar:

William Eggleston: You know, I had a meeting with him [Henri Cartier-Bresson], one in particular, it was at this party in Lyon. Big event, you know. I was seated with him and a couple of women. You’ll never guess what he said to me.

Drew Barrymore: What?

William Eggleston: “William, color is bullshit.” End of conversation. Not another word. And I didn’t say anything back. What can one say? I mean, I felt like saying I’ve wasted a lot of time. As this happened, I’ll tell you, I noticed across the room this really beautiful young lady, who turned out to be crazy. So I just got up, left the table, introduced myself, and I spent the rest of the evening talking to her, and she never told me color was bullshit.

Esse tipo de dissidência é comum no processo criativo, é pressuposto e importante que surjam diversas linhas de pensamento. Em computação, estamos sempre procurando convergir para uma solução ótima, é desconfortável aceitar que existam múltiplos caminhos sem um vencedor claro. É importante estar confortável com divergências, porque qualidade de código é sobre os outros.

Se formos definir o principal motivo para fazer códigos limpos, é que seja possível modificá-lo no futuro. Um código que nunca será alterado, é indiferente a essa questão. Em geral, a ideia é que várias pessoas consigam mexer no código, não somente o autor. Logo, a sua ideia de código limpo precisa ser compartilhada com outras pessoas que trabalharão nele, senão ela perde o sentido.

Quando comecei a trabalhar na área de dados, passei a lidar com profissionais e problemas mais heterogêneos e isso me ajudou a enxergar a importância do contexto nas discussões sobre código. Por exemplo, o que é código limpo para esse cenários:

1. cientistas de dados acostumados com programação vetorial, preparando dados para entrada em uma rede neural;

2. analista de negócio, querendo apenas substituir uma planilha Excel cheia de macros por um Jupyter Notebook;

3. desenvolvedor back-end acostumado com conceitos como DTOs, polimorfismo, interfaces, injeção de dependência, etc.

A melhor solução para cada problema, provavelmente é um anti-pattern para os demais. Por exemplo, normalmente prefiro manter códigos repetidos ao invés de usar polimorfismo no cenário (2), o que não faria sentido para o cenário (3).

Obviamente tenho minhas preferências, mas elas não sobrepõem as necessidades dos “clientes” do meu código, as pessoas que precisarão mantê-lo. Não existe código limpo a priori – o que está sendo feito e para quem – definem o que é ser limpo.

Não se abstenha

O meu argumento é que devemos conviver melhor com diversas perspectivas de código limpo, mas há um risco em adotar uma postura muito flexível. Abster-se de uma decisão e acabar com um código insustentável para manter.

É importante identificar as brigas corretas, afinal discussões podem ser cansativas e gerar desgastes, não queremos gastar energia com debates infrutíferos. Infelizmente, não sei dizer um modo de diferenciar os cenários: esse código é ruim e insustentável ou é simplesmente diferente do que estou acostumado?

Só posso sugerir criação de repertório para responder essa pegunta, explorar problemas e tecnologias diferentes com a cabeça aberta. Dar-se um tempo para se sentir confortável, tomar cuidado para não adotar posições dogmáticas prematuras. Por fim, o mais difícil: aceitar que nem sempre iremos gostar.

Willian Eggleston pôde seguir com sua fotografia colorida, a despeito da opinião de Henri Cartier-Bresson sobre ela. Você também pode seguir suas preferências em seu projeto pessoal, mas não em um contexto profissional. Assim como artistas fazem concessões em trabalhos comerciais, devemos fazer o mesmo pelo time.

Sugeri inspiração no processo criativo para desenvolvimento de software, mas essa é uma diferença fundamental: o seu código deve ser limpo para os outros, não para você. Seja lá, o que código limpo significa.

Ler dados de um tópico Kafka costuma ser bem rápido, rápido demais inclusive. Ao consumir um tópico, o problema costuma variar entre dois extremos: baixo throughput, porque a aplicação quer manter um consumo exactly-once sem concorrência/paralelismo, ou overflow do consumidor porque ela está lendo mais rápido do que consegue processar.

Quando o assunto Kafka é abordado, discute-se muito as questões de infra do ambiente (e.g. número de partições, réplicas e picos de uso). O que pretendo abordar nesse post, é o lado de desenvolvimento, como construir e escalar uma aplicação que consome os dados a partir de um tópico.

Primeiro, farei uma breve introdução a eventos e conceitos básicos importantes para se trabalhar com Kafka. Depois, propor um problema hipotético e entender as abordagens possíveis. Por fim, implementar as possíveis soluções para tangibilizar a discussão em números e código.

Por que eventos?

A ideia de eventos se popularizou bastante nos últimos anos e um cenário em que ela funciona muito bem, é o problema de mensageria: quando algo acontece no sistema, uma compra confirmada em um sistema de e-commerce por exemplo, é necessário notificar o usuário via e-mail.

A solução imediata é fazer uma integração síncrona via API, confirmando a compra após finalizar todas etapas, incluindo o envio do e-mail.

Mesmo em uma escala pequena, esse tipo de solução normalmente incorre em uma série de problemas:

• enviar e-mails é um processo demorado e deixar uma requisição “presa” enquanto espera o envio, pode sobrecarregar tanto os sistema de vendas quanto a mensageria;

• é comum usar serviços externos para envio de e-mails, o que aumenta problemas de latência e riscos de indisponibilidade;

• nem sempre as comunicações precisam (ou devem) ser enviadas logo após a compra, comunicações e canais podem ter políticas de envio complexas;

• o e-mail normalmente não é parte crítica do processo: faz mais sentido vender e não enviar o e-mail, do que perder uma venda por não conseguir enviar o e-mail.

Dado esse cenário, é normal partir para uma solução orientada a eventos, adicionando um message broker para mediar a comunicação entre o transacional e a mensageria.

Nessa solução, o sistema de vendas coloca na fila os e-mails que precisam ser enviados, mas não aguarda o envio pela mensageria. Ao desacoplar os processos e adotar uma arquitetura orientada a eventos, temos uma série de vantagens:

• postar mensagens em um broker, costumar ser uma operação simples e estável. Isso torna o sistema de vendas mais rápido, mais fácil de dimensionar e escalar;

• o envio de e-mails – um processo complexo e demorado – não precisa mais ser dimensionado para o pico, apenas o broker precisa suportar o pior caso;

• apesar do broker ser uma peça a mais para manter, na prática costuma ser mais simples garantir a disponibilidade de um broker que de um sistema como a mensageria.

Por outro lado, temos desvantagens, especialmente pensando nas garantias de sucesso:

• o sistema de vendas não sabe quando o e-mail foi enviado, nem mesmo se houve problemas no envio;

• a observabilidade é mais difícil por envolver mais peças, especialmente erros que envolvem perda de mensagens;

• programação assíncrona é mais complexa que síncrona, esse tipo de solução costuma ser um ônus para os desenvolvedores.

A questão é ponderar esses trade-offs, o exemplo da mensageria é um cenário em que faz bastante sentido usar eventos, mas em outros casos pode ser necessário uma análise mais criteriosa antes de adotar uma abordagem assíncrona.

O cenário proposto é um exemplo de comunicação ponta a ponta usando eventos, mas é comum existir a necessidade de mútiplos consumidores. Por exemplo, além de enviar os eventos para o sistema de mensageria, salvar o que foi enviado em um ambiente analítico. Para lidar com esse cenário, uma opção interessante é usar o conceito de tópicos ao invés de filas.

Fila ou PubSub?

O padrão para comunicação ponta-a-ponta, é utilizar uma fila: o broker mantém as mensagens guardadas até que o consumidor dê um “ack”, indicando que uma mensagem específica pode ser removida.

O problema é que esse padrão não suporta múltiplos consumidores, é necessário replicar e alimentar a fila para cada consumidor adicional. Não é uma solução escalável, já que a quantidade de mensagens cresce em função do número de consumidores.

A alternativa, para lidar com um cenário de múltiplos consumidores, é utilizar a abordagem PubSub adotada pelo Kafka. Nesse modelo, o broker guarda o conteúdo por um tempo determinado (e.g. 7 dias), fica a cargo da aplicação consumidora controlar o offset para saber o que foi lido.

No cenário acima, temos dois consumidores, cada um com um offset diferente. Como mandar e-mails é um processo mais demorado que salvar no ambiente analítico, então é normal o offset da mensageria ficar “atrasado” em relação ao processo analítico.

Essa abordagem de PubSub é mais flexível, pois facilita o cenário de múltiplos consumidores, que é uma demanda bastante comum. Por que utilizar filas então, se existe essa limitação de um único consumidor? A simplicidade é o principal motivo, já que o paradgima PubSub tem vários detalhes que precisam ser tratados.

Ao trabalhar com offsets, existem diferentes formas de lidar com a atualização a depender das semânticas de consumo: at-most-once, exactly-once e at-least-one. Usando filas, basta dar um “ack” para garantir um consumo exactly-once.

Arquitetos e programadores

Em geral, os trade-offs de síncrono e assíncrono se repetem, independente do problema de negócio e do tipo de broker utilizado. Da perspectiva de arquitetura, quase sempre é melhor ser assíncrono e no modelo PubSub, mas programadores ficam ressabiados com os desafios de implementação.

Arquitetos se preocupam muito com escalabilidade e custos, pontos fortes da comunicação assíncrona. Para os desenvolvedores, por outro lado, é necessário mais esforço para sustentação e os desafios de desenvolvimento são maiores.

O mundo seria mais simples para programadores, se os sistemas fossem sempre integrados usandos APIs REST síncronas, mas a realidade é que precisamos lidar com tópicos e o paradigma PubSub.

Semânticas de consumo

A mensageria é um problema que se encaixa bem com a ideia de eventos, mas é necessário cuidado ao usar tópicos no lugar de filas. A forma de lidar com o consumo depende da natureza da comunicação, uma decisão que precisa ser tomada com o negócio em vista.

Podemos consumir um tópico seguindo uma dessas semânticas:

• at-most-once significa que a mensagem será consumida no máximo uma vez, mas pode ser perdida;
• at-least-once significa que todas as mensagens serão consumidas uma vez, mas podem ser consumidas mais de uma vez;
• exactly-once significa que todas as mensagens serão consumidas uma única vez.

O ideal seria tudo ser exactly-once, mas não é algo que vem de graça. Para garantir essa semântica, é necessário um controle externo de offsets e há limites para a escalabilidade do consumidor, enquanto as outras abordagens são mais simples e escaláveis.

Considerando o cenário de e-mails para confirmação de compra, é interessante pensar na abordagem exactly-once, mesmo com as dificuldades:

• mensagens enviadas por e-mails, normalmente não demandam urgência e são pouco volumosas, o que reduz os problema de escalabilidade;

• por outro lado, enviar e-mails repetidos é algo ruim para experiência e pode ser classificado como spam pelos serviços;

• no cenário de um fluxo de compras, perder mensagens com comprovantes pode ser problemático para o consumidor e o negócio.

Essa discussão seria muito diferente, se pensarmos em mensageria de notificações para uma rede social por exemplo, que normalmente é um cenário de grande volume e menor criticidade. As vantagens de escalabilidade de uma abordagem at-most-once ou at-least-once podem ser indispensáveis, mesmo que exista o risco de perder ou repetir notificações.

Garantindo exactly-once

Começando pelo cenário exactly-once, podemos nos basear na solução do tutorial da Confluent, que é a implementação mais simples possível de um consumidor.

try:

    while True:

        msg = consumer.poll(timeout=1.0)
        if msg is None: continue

        process_message(conn, msg.value().decode())

finally:
    consumer.close()

Nessa solução, cada mensagem consumida é processada logo em seguida, mas não há controle explícito dos offsets. Como o objetivo é trabalhar com exactly-once, o ideal é desativar o commitautomático. O consumidor deve controlar a atualização manualmente e de forma síncrona programaticamente.

try:

    count = 0    
    start_time = datetime.now()

    while True:

        msg = consumer.poll(timeout=1.0)
        if msg is None: continue

        process_message(conn, msg.value().decode())

        consumer.commit() # Commit explícito para cada mensagem

finally:
    consumer.close()

Nesse código, aparentemente é garantido o consumo exactly-once, mas e se houver um erro ao executar process_message? Nesse cenário, se faz necessário controle externo – fila morta, banco de dados, cache – para guardar as mensagens que deram erro.

try:

    count = 0    
    start_time = datetime.now()

    while True:

        msg = consumer.poll(timeout=1.0)
        if msg is None: continue

        ok = process_message(conn, msg.value().decode())

        if not ok:
          dlq(msg) # Salvando mensagens em uma dlq (dead letter queue)

        consumer.commit()

        if count == num_records: break

finally:
    consumer.close()

Sem um controle externo para salvar as mensagens com erro, é necessário parar o processamento do tópico: não é possível atualizar o offset para a mensagem \(x_{i}\), se existe uma mensagem \(x_{j}\) \(\forall j < i\) não processada.

Para esse cenário exactly-once, as filas costumam funcionar melhor, já que as mensagens são controladas individualmente e não por offsets. Soluções de fila, como SQS da Amazon e RabbitMQ por exemplo, têm o recurso de fila morta para facilitar a gestão de mensagens problemáticas.

No caso do tópico Kafka, o usuário precisa estar ciente desse problema e implementar uma solução por fora. Ou seja, é possível implementar a semântica exactly-once em tópicos, mas é necessário cuidado com offsets e talvez demande ferramentas extras para o tratamento adequado de erros.

Apesar de não ser a melhor estratatégia para consumir um tópico, recomendo começar pela semântica exactly-once até que necessidades de escalabilidade apareçam. As outras semânticas podem trazer ganhos expressivos, mas criam outras dificuldades e perde-se garantias.

Um equívoco comum, quando surge a necessidade de escalar um consumidor Kafka, é misturar a leitura do tópico com o processamento da mensagem. É importante entender essa diferença, porque a solução dos problemas vão em direção oposta: aumentar o throughput de leitura, quando o gargalo é de processamento, poder causar overflow no consumidor.

A ideia é discutir os gargalos de processamento das mensagens, não do consumo propriamente dito, pois vejo poucas discussões sobre o assunto e muitas dificuldades por parte dos desenvolvedores. É uma questão que depende muito do problema a ser resolvido – aplicar um modelo de machine learning, salvar as mensagens em um banco de dados e agregar informações são tarefas muito diferentes – mas existem estratégias que podem ser aplicadas otogonalmente à natureza do problema.

Um problema “I/O bound”

Voltando ao nosso cenário de mensageria, imagine que essas mensagens precisem ser salvas em um banco de dados, para uso analítico e acompanhamento da operação. A solução é consumir continuamente as mensagens postadas no tópico e salvá-las em uma tabela do PostgreSQL.

Para ilustrar o problema, a estratégia foi produzir mensagens aleatórias serializadas como json em um tópico. Abaixo, um exemplo de mensagem gerada.

{
    "message_id": "2268086d-5d3f-40e2-80ce-fc9f4e3008dc",
    "client_id": "8592b337-168e-4304-82d3-0d36b556e58b",
    "products": [
        {
            "sku": "d33b284b-c62e-47d7-b8e8-2048fe2d9da5",
            "price": 100,
            "quantity": 2
        },
        {
            "sku": "aebbb957-e16e-43d2-b742-198c12ef96a8",
            "price": 16387,
            "quantity": 4
        },
        {
            "sku": "9f8c0bfe-5e9b-4822-84b7-7b8e86a6469d",
            "price": 6750,
            "quantity": 2
        },
        {
            "sku": "79c5824b-ac16-4b59-8bda-31328a0204ec",
            "price": 100,
            "quantity": 5
        }
    ]
}

Para geração dessas mensagens, o script abaixo foi utilizado.

def create_sample():
    
    σ_price = 2_000
    μ_price = 10_000

    quantity_range = (1,10)
    products_range = (1,5)

    return {
        'message_id': str(uuid4()),
        'client_id': str(uuid4()),
        'products': [{"sku": str(uuid4()),
                      "price": max(100,
                                   int(σ_price + np.random.randn() * μ_price)),
                      "quantity": np.random.randint(*quantity_range)}
                     for _ in range(np.random.randint(*products_range))]
    } 

As mensagens serão salvas em uma tabela, com dois campos (message_id e client_id) que armazenam dados extraídos da mensagem e uma coluna de content para guardar o conteúdo original do tópico.

create table messages(message_id char(36) primary key, 
                      client_id char(36),
                      datetime timestamp,
                      content text)

Para salvar a mensagem, será utilizada essa função, que faz um parse do json e insere na tabela que foi descrita.

def save_message(conn, msg: str) -> callable:

    content =  json.loads(msg)

    values = (
        content['message_id'],
        content['client_id'],
        datetime.now(),
        msg,
    )

    insert = "insert into messages VALUES (%s, %s, %s, %s)"

    with conn.cursor() as cur:
        cur.execute(insert, values)

    conn.commit()

O problema proposto é I/O bound e facilmente paralelizável, um cenário comum em sistemas de informação e que podemos ter ganhos expressivos de performance com um bom desenho de solução.

Os limites do exactly-once

A primeira opção para resolver esse problema, é utilizar a solução do consumidor exactly-once, substituindo a função process_message pela save_message.

try:
    count = 0

    while count < num_records:
        
        msg = consumer.poll(timeout=1.0)
        if msg is None: continue

        save_message(conn, msg.value().decode())

        count+=1
        consumer.commit()
finally:
    conn.close()

Para inserir 1.000.000 de registros, esse script demorou 47 minutos. O gargalo desse processo é escrever no banco de dados. Removendo a etapa de inserção – mas mantendo o pull das mensagens, parse e formatação para o modelo de dados – o processo demorou 16 segundos.

Fiz esse experimento, para ilustar que esse é um cenário de problemas com o processamento da mensagem. Otimizações no consumo e/ou brokers não fazem sentido, já que essa parte está ocupando uma pequena fração do tempo total de processamento.

Asyncio para remover o gargalo

A lentidão dessa solução é devido a ausência de concorrência, executar esse tipo de trabalho de forma sequencial é um desperdício em dois sentidos:

• o processo do consumidor fica pausado, enquanto espera salvar no banco de dados;

• os bancos de dados normalmente são desenhados para lidar bem com escritas concorrentes, escrever vários registros sequencialmente não tira proveito disso.

Existem várias alternativas para implementar concorrência em Python, uma delas é o uso de asyncio para trabalhar com tarefas em segundo plano. Essa estratégia depende do suporte das bibliotecas utilizadas, então nem sempre é possível utilizá-la.

A biblioteca psycopg, utilizada para conexão com o banco de dados, tem suporte a asyncio. A função save_message foi re-escrita de forma assíncrona como asave_message.

async def asave_message(aconn, msg: str):
    
    async with aconn.cursor() as acur:

        content =  json.loads(msg)

        values = (
            content['message_id'],
            content['client_id'],
            datetime.now(),
            msg,
        )

        insert = "insert into messages VALUES (%s, %s, %s, %s)"

        await acur.execute(insert, values)

A programação assíncrona com asyncio tem vários conceitos como tarefas, corotinas, etc – eu mesmo tenho uma compreensão superficial – então recomendo a documentação e outros materiais, caso o leitor queira entender melhor a implementação. Não é necessário compreender a implementação para a leitura do post, mas é interessante entender a ideia do que está acontecendo após essa mudança.

Na versão assíncrona, o processo não espera o término da inserção pra iniciar as demais. Aproveita-se melhor o tempo de CPU e o tempo total de execução é bem reduzido, considerando que o banco de dados lida bem com escritas concorrentes.

Usando execução assíncrona, é preciso tomar cuidado com o overflow de mensagens. Se iniciarmos uma task para cada mensagem que chega, o consumidor pode ter problemas ao lidar com rajadas e cenários de dados represados e/ou reprocessamento.

A estratégia de micro-batches é um jeito fácil de lidar com esse problema, que consiste em gerar pequenos lotes a partir do fluxo contínuo. No código abaixo, a função consume puxa até BACTH_SIZE registros do tópico a cada iteração. A variável timeout é utilizada para configurar a latência máxima: se não houver BATCH_SIZE registros a serem puxados em 1 segundo, um batch menor será criado e executado.

try:

    count = 0

    while count < num_records:
    
        msgs = consumer.consume(BATCH_SIZE, timeout=1.0)
        if len(msgs) == 0: continue
        
        msgs_content = map(lambda x : x.value().decode(), msgs)

        await asave_messages(msgs_content)

        count+=len(msgs)
        consumer.commit()
finally:
    consumer.close()

A função asave_messages é responsável por lançar as tasks de asave_message, o await indica que o loop principal precisa esperar todas as mensagens serem processadas antes de buscar outro lote de mensagens.

async def asave_messages(msgs: list[str]):
    
    aconn = await psycopg.AsyncConnection.connect(db)

    async with aconn:
        async with asyncio.TaskGroup() as tg:
            for msg in msgs:
                tg.create_task(asave_message(aconn, msg))

        await aconn.commit()

O micro-batch é uma estratégia para ter previsibilidade no consumidor, que pode ser configurado e dimensionado de acordo com uma taxa fixa e latência esperada, apenas o broker que precisar lidar com picos de volumetria e eventuais anomalias. Perde-se um pouco em latência, mas é o trade-off esperado em uma arquitetura de eventos.

Nesse cenário, não existe mais uma garantia de exactly-once. Se houver algum erro durante o processamento do batch, o usuário deve optar por não atualizar os offsets e adotar uma semântica at-least-once ou atualizá-los e adotar uma semântica at-most-once. No cenário proposto, faz sentido adotar at-least-once, pois o banco de dados garante idempotência da operação de insert.

Usando BATCH_SIZE=10_000, o tempo total foi de 47 minutos para cerca de 3 minutos

A alternativa multiprocess

O asyncio é a solução desenhada para esse cenário de muito I/O concorrente, mas existem bons motivos para usar outros métodos de implementar concorrência, como multiprocess e threading.

O principal motivo é que a implementação assíncrona depende que as bibliotecas utilizadas a suportem, o que não é tão prevalente no ecossistema Python. Além disso, existem muitos conceitos complexos em programação assíncrona e isso reflete na dificuldade de implementação.

Processamento paralelo em Python é uma questão conteciosa pela existência do GIL, a decisão entre threads e processos normalmente é definida pela natureza do processamento. Sendo um processo I/O bound, eu poderia optar por threads que são mais leves e fáceis de se comunicar, mas optei por paralelizar com processos pelos seguintes motivos:

• é um cenário clássico de data paralelism, as dificuldades de comunicação entre processos não são releventes nesse contexto;

• usando pool de processos, o problema do custo extra de criar múltiplos processos é mitigado;

• prefiro evitar pensar sobre questões de thread safety, vou usar um hack para criar objetos separados por processo e ignorar esse problema;

• a solução pode ser aplicada em cenários CPU bound, se quiséssemos aplicar modelos de machine learning por exemplo.

A estratégia de usar vários processos, é aproveitar a interrupção do sistema operacional para operar de forma concorrente: quando um processo chega na etapa de I/O, ele é interrompido e outro entra em execução. No caso do asyncio, estamos usando um único processo Python que implementa concorrência usando Tasks.

A maior complicação de usar multiprocess nesse problema, é lidar com a conexão com o banco de dados. Não é possível compartilhar esse tipo de objeto entre processos, mas é contraproducente ficar recriando a conexão a cada iteração.

A solução é criar um objeto por processo, que será utilizado até o fim do batch. Não é a forma mais elegante, mas um jeito é criar uma variável vazia conn e inicializar como global usando a função set_global_conn.

conn = None

def set_global_conn():
    global conn
    conn = psycopg.connect(db)

Abaixo, a implementação do proceso usando set_global_conn na criação do pool de processos.

def save_messages_conn(msgs: list[str]): save_message_batch(conn, msgs)

try:

    count = 0

    while count < num_records:

        msgs = consumer.consume(BATCH_SIZE, timeout=1.0)
    
        if len(msgs) == 0: continue
        
        msgs_content = map(lambda x : x.value().decode(), msgs)

        with Pool(processes=48,
                  initializer=set_global_conn) as pool:

            pool.map(save_message_conn, msgs_content)

        count+=len(msgs)
        consumer.commit()

finally:
    consumer.close()

Em termos de desempenho, essa solução ficou parecida com a implementada utilizando asyncio. Ambos ficaram perto dos 2 minutos, mas o desempenho do multiprocess demanda mais processamento e está condicionada a configuração de núcleos da máquina.

As estratégias aplicadas até o momento, foram para agilizar as operações de I/O, mas podemos reduzir a quantidade de operações também.

Reduzindo o custo fixo

As operações de I/O têm um custo fixo – não importa a quantidade de dados transmitido, sempre é necessário interromper o processamento e lidar com o overhead do protocolo – faz sentido agrupar as operações e dissolver esse custo.

Quando se faz aplicações em lote para trabalhar com banco de dados, é sempre recomendado aplicar estratégias que tirem proveito dessa ideia. Desde ações simples, como não executar o commit para toda linha modificada, seja ações mais agressivas como remover índices durante o processamento e recriá-los posteriormente.

Nesse caso, a ideia é simplesmente agrupar os inserts em pequenos grupos e não chamar commit a cada linha inserida. É bem simples fazer isso com psycopg, basta criar uma lista de valores e usar o comando executemany no cursor.

def save_message_batch(conn, msgs: list[str]):

    values = []

    for msg in msgs:
    
        content =  json.loads(msg)

        values.append((
            content['message_id'],
            content['client_id'],
            datetime.now(),
            msg,
        ))

    insert = "insert into messages VALUES (%s, %s, %s, %s)"

    with conn.cursor() as cur:
        cur.executemany(insert, values)
        
    conn.commit()

No consumidor, é necessário criar esses grupos de mensagens a serem inseridas. Como as mensagens são independentes entre si, os grupos podem ser criados de forma arbitrária aplicando cortes no vetor.

if num_msgs <= BATCH_INSERT:
    chunks = [msgs_content]
else:
    chunks = [
        msgs_content[
            i*BATCH_INSERT:
            (i*BATCH_INSERT)+BATCH_INSERT
        ]
        for i
        in range(num_msgs // BATCH_INSERT + 1)]

Exceto pela criação dos chunks, a estrutura do consumidor fica praticamente igual às demais implementações.

try:

    count = 0

    while count < num_records:
    
        msgs = consumer.consume(BATCH_SIZE, timeout=1.0)
        num_msgs = len(msgs)

        if num_msgs == 0: continue
    
        msgs_content = list(map(lambda x : x.value().decode(), msgs))

        if num_msgs <= BATCH_INSERT:
            chunks = [msgs_content]
        else:
            chunks = [
                msgs_content[
                    i*BATCH_INSERT:
                    (i*BATCH_INSERT)+BATCH_INSERT
                ]
                for i
                in range(num_msgs // BATCH_INSERT + 1)]

        with Pool(processes=48,
                  initializer=set_global_conn) as pool:
            pool.map(save_message_batch_conn, chunks)

        count+=num_msgs
        consumer.commit()

finally:
    consumer.close()

Essa implementação com operações agrupadas, ficou ainda mais performática – usando BATCH_INSERT = 35, BATCH_SIZE = 10_000 e 48 processos – o processo todo demorou 40 segundos para inserir 1.000.000 de registros, o que antes demorava 47 minutos.

Capcioso

Eu não esperava que essas mudanças trouxesse ganhos tão expressivos, mas naturalmente esses resultados dependem de uma miríade de fatores. Para quem quiser executar os experimentos ou adaptar a solução para outro cenário, os códigos estão nesse repositório.

A ideia do post não era discutir esse problema em específico, mas as tomadas de decisão ao construir um consumidor Kafka. Os códigos desenvolvidos não são trabalhosos, nem mesmo complexos. Capciosos, talvez?

São códigos curtos, mas que demandam entendimento de concorrência e paralelismo, conceitos considerados avançados. O truque, de usar uma variável global não inicializada para criar um objeto por processo, é algo simples de implementar. Só que não é óbvio entender o porquê não se pode serializar uma conexão com banco de dados, nem o porquê isso é necessário quando se trabalha com múltiplos processos.

Problemas de engenharia de dados têm essa característica, mas até pela natureza de lidar com grandes volumes, é comum esses gargalos óbvios sejam discutidos em materias introdutórios. No caso do Kafka, essa discussão existe, mas muita mais sobre a infra do broker (e.g partições, réplicas, ZooKeeper, storage).

Imagino que um dos motivos, para não existir tantas discussões sobre a arquitetura do consumo, seja a grande variedade de aplicações. As discussões mudariam completamente se, por exemplo, o problema consistisse de eventos dependentes entre si. Mesmo assim, enxergo que existem padrões a serem seguidos em praticamente qualquer cenário, como a ideia de micro-batch para não ter problemas de overflow e abrir possibilidades de otimização.

Espero ter conseguido passar a ideia, dos pontos de atenção a serem considerados ao desenhar um consumidor. É um post que acabou maior que o esperado, mas o diabo está nos detalhes quando se fala de Goethe Kafka, então achei importante expandir alguns tópicos para além do código e resultados.

Imagino ser um cenário comum – encontrar cientistas, analistas e afins – sofrendo desnecessariamente com tabelas enormes armazenadas em formato texto (e.g. csv, json). São formatos práticos e acessíveis, ótimos para pequenos projetos, mas que não escalam bem para grandes volumes.

Uma das alternativas mais comuns para dados tabulares, é utilizar arquivos parquet. Mas o que são esses arquivos? Após anos usando parquet, tendo uma vaga noção do que se trata, surgiu a curiosidade de entender mais profundamente os detalhes de implementação.

A proposta do Parquet

O formato parquet foi proposto pelo Twitter, em parceria com a Cloudera, como um formato otimizado para uso no ecossistema Hadoop. As ideias de design por trás do formato são discutidas nessa apresentação, entre as mais importantes delas:

• encoding e compressão a nível de coluna, dando flexibilidade para otimizações;
• formato colunar, ideal para workloads analíticos;
• especificação aberta e agnóstica de plataforma.

Na especificação do formato, tem um diagrama que apresenta a estrutura geral do arquivo (Figura 1).

Olhando somente o diagrama, não consegui entender muito bem o formato, então optei pela estratégia de ler o código de alguma implementação. Uma ideia que acabou se mostrando bem mais complicada que o esperado, mas após muito debug e leitura de especificações, consegui entender o formato e gerar um arquivo parquet “na unha”.

Fastparquet como referência

Sendo um formato aberto, existem diversas implementações diferentes para leitura e escrita de arquivos parquet, como Arrow e Spark por exemplo. Optei pelo fastparquet, que é uma implementação puramente em Python e me permitiria debugar passo-a-passo se necessário.

Para analisar o código, fui executando linha-a-linha o comando write('outfile.parquet', df, append=False), usando a tabela abaixo.

Após executar várias vezes, consegui formar uma noção melhor da especificação. Agora, a ideia é fazer uma implementação “minimalista” em Go: transformar essa tabela em um arquivo parquet, da forma mais simples possível.

Sobre os metadados

Os metadados de um arquivo parquet são escritos usando o Thrift Compact Protocol, um tipo de serialização utilizado pelo protocolo RPC Thrift. É similar a outros protocolos de serialização, como Protobuf e Avro por exemplo.

Para quem não está familiarizado com esses protocolos, são especificações de serialização binária, otimizadas para processamento/armazenamento em comparação a formatos texto. Em contrapartida, não são amigáveis para leitura do usuário, como um json ou yaml.

Para ler e escrever em Thrift Compact Protocol, precisamos de uma especificação, um schema com a estrutura da informação. Esse arquivo é a especificação dos metadados de um arquivo parquet, uma representação gráfica da estrutura pode ser vista na figura abaixo.

Criando uma página

A primeira parte de um arquivo parquet são as páginas de dados. Cada página contém dados de uma única coluna, uma coluna pode estar separada em várias páginas. Em nosso caso, será apenas uma página por coluna, na qual o dado será armazenado sem compactação e com representação PLAIN.

Cada página de dados tem um cabeçalho, representado pelo objetos PageHeader e DataPageHeader:

pageHeader := PageHeader{
		pageType:             0 /* DATA_PAGE */,
		uncompressedPageSize: int32(content.Len()),
		compressedPageSize:   int32(content.Len()),
		dataPageHeader: DataPageHeader{
			numValues: int32(len(column)),
			encoding:  0 /* PLAIN */}}

Para criar esse cabeçalho, é necessário saber o tamanho da página e a quantidade de registros. Portanto, antes de escrever o cabeçalho de uma página, é necessário lidar com o conteúdo dela.

Escrevendo a coluna de strings em PLAIN text

As colunas da tabela serão tratadas como strings binárias, que podem ser representadas como BYTE_ARRAY em um arquivo parquet. Usando a representação PLAIN, basta informar o tamanho do array de bytes e escrever o conteúdo em seguida.

BYTE_ARRAY: length in 4 bytes little endian followed by the bytes contained in the array

Abaixo, o código utilizado para escrever uma coluna. Para cada item da coluna, o tamanho é calculado e representado como um inteiro em 4 bytes. O conteúdo é escrito logo após, sem nenhuma transformação.

type Parquet struct {
	writer    thrift.TProtocol
	file      io.ReadWriter
	ctx       context.Context
	transport *thrift.StreamTransport
}

func (t *Parquet) writeColumn(records [][]byte) {

	for _, record := range records {

		valueSize := uint32(len(record))

		size := make([]byte, 4)
		binary.LittleEndian.PutUint32(size, valueSize)
		t.file.Write(size)
		t.file.Write(record)
	}

	t.transport.Flush(t.ctx)

}

Juntando no arquivo

Como é necessário saber o tamanho do conteúdo para criar o cabeçalho da página, foram usados dois buffers apartados: header e content. O content é criado antes do header, mas no arquivo é escrito na ordem inversa.

func WritePage(column [][]byte, f *os.File) int {

	header := bytes.NewBuffer([]byte{})
	content := bytes.NewBuffer([]byte{})

	parquetHeader := TableParquet(header)
	defer parquetHeader.transport.Close()

	parquetContent := TableParquet(content)
	defer parquetContent.transport.Close()

	parquetContent.writeColumn(column)

	pageHeader := PageHeader{
		pageType:             DATA_PAGE,
		uncompressedPageSize: int32(content.Len()),
		compressedPageSize:   int32(content.Len()),
		dataPageHeader: DataPageHeader{
			numValues: int32(len(column)),
			encoding:  0 /* PLAIN */}}

	parquetHeader.writePageHeader(pageHeader)
	pageSize := content.Len() + header.Len()

	bufferToFile(header, f)
	bufferToFile(content, f)

	return pageSize
}

Utilizando a biblioteca em Go, a função writePageHeader escreve o objeto thrift PageHeader.

func (t *Parquet) writeI32(name string, id int16, value int32) {

	t.writer.WriteFieldBegin(t.ctx, name, thrift.I32, id)
	t.writer.WriteI32(t.ctx, value)
	t.writer.WriteFieldEnd(t.ctx)
}

func (t *Parquet) writeDataPageHeader(dataPageHeader DataPageHeader) {

	t.writer.WriteStructBegin(t.ctx, "DataPageHeader")

	t.writeI32("num_values", 1, dataPageHeader.numValues)
	t.writeI32("encoding", 2, dataPageHeader.encoding)
	t.writeI32("definition_level_encoding", 3, dataPageHeader.definitionLevelEncoding)
	t.writeI32("repetition_level_encoding", 4, dataPageHeader.repetitionLevelEncoding)

	t.finishStruct()
}

func (t *Parquet) writePageHeader(pageHeader PageHeader) {

	t.writer.WriteStructBegin(t.ctx, "PageHeader")

	t.writeI32("type", 1, int32(pageHeader.pageType))
	t.writeI32("uncompressed_page_size", 2, pageHeader.uncompressedPageSize)
	t.writeI32("compressed_page_size", 3, pageHeader.compressedPageSize)

	t.writer.WriteFieldBegin(t.ctx, "data_page_header", thrift.STRUCT, 5)
	t.writeDataPageHeader(pageHeader.dataPageHeader)
	t.writer.WriteFieldEnd(t.ctx)

	t.finishStruct()
}

Ao final, a página da primeira coluna é representada da seguinte forma no arquivo.

00000000  50 41 52 31 15 00 15 42  15 42 2c 15 06 15 00 15  |PAR1...B.B,.....|
00000010  00 15 00 00 00 07 00 00  00 63 68 61 76 65 5f 31  |.........chave_1|
00000020  07 00 00 00 63 68 61 76  65 5f 32 07 00 00 00 63  |....chave_2....c|
00000030  68 61 76 65 5f 33                                 |have_3|
00000036

Escrevendo o rodapé

Diferente da maioria dos formatos, para ler um parquet começamos pelo rodapé. As colunas e seus tipos são especificados pelo schema, enquanto os detalhes das páginas geradas ficam nos row_groups.

Abaixo o código para escrita completa do arquivo, primeiro as páginas são geradas, para depois criar a estrutura do footer indicando a posição delas no arquivo.

f, _ := os.Create("sample.parquet")
defer f.Close()

footer := bytes.NewBuffer([]byte{})
parquetFooter := TableParquet(footer)
defer parquetFooter.transport.Close()

magicBytes(f)

sizeKeys := WritePage(keys, f)
sizeValues := WritePage(values, f)
numRows := len(records)

magicBytesOffset := 4

schema := []SchemaElement{
    {name: "schema", numChildren: 2},
    {name: "key", colType: 6 /*BINARY ARRAY*/}, 
    {name: "values", colType: 6 /*BINARY ARRAY*/}}

columns := []ColumnChunk{
    {fileOffset: int64(magicBytesOffset),
        metaData: ColumnMetadata{
            columnType:            6 /*BINARY ARRAY*/,
            encodings:             []int32{0},
            pathInSchema:          []string{"key"},
            codec:                 0,
            numValues:             int64(numRows),
            totalUncompressedSize: int64(sizeKeys),
            totalCompressedSize:   int64(sizeKeys),
            dataPageOffset:        int64(magicBytesOffset),
            statistics:            Statistics{nullCount: 0},
        },
    },
    {fileOffset: int64(magicBytesOffset + sizeKeys),
        metaData: ColumnMetadata{
            columnType:            6 /*BINARY ARRAY*/,
            encodings:             []int32{0},
            pathInSchema:          []string{"values"},
            codec:                 0,
            numValues:             int64(numRows),
            totalUncompressedSize: int64(sizeValues),
            totalCompressedSize:   int64(sizeValues),
            dataPageOffset:        int64(magicBytesOffset + sizeKeys),
            statistics:            Statistics{nullCount: 0},
        },
    },
}

parquetFooter.writeFileMetadata(
    FileMetaData{
        version:  1,
        schema:   schema,
        num_rows: int64(numRows),
        row_groups: []RowGroup{
            {columns: columns,
                totalByteSize: int64(sizeKeys + sizeValues),
                numRows:       int64(numRows)},
        },
    },
)

Após escrever o footer no arquivo como um objeto Thrift, é necessário escrever o seu tamanho como um inteiro de 4 bytes. Isso é importante, porque o consumidor utiliza esse número para identificar onde o rodapé começa.

bs := make([]byte, 4)
binary.LittleEndian.PutUint32(bs, uint32(footer.Len()))
parquetFooter.file.Write(bs)

No final, o arquivo completo completo, com as duas colunas e o rodapé ficou da seguinte forma.

00000000  50 41 52 31 15 00 15 42  15 42 2c 15 06 15 00 15  |PAR1...B.B,.....|
00000010  00 15 00 00 00 07 00 00  00 63 68 61 76 65 5f 31  |.........chave_1|
00000020  07 00 00 00 63 68 61 76  65 5f 32 07 00 00 00 63  |....chave_2....c|
00000030  68 61 76 65 5f 33 15 00  15 42 15 42 2c 15 06 15  |have_3...B.B,...|
00000040  00 15 00 15 00 00 00 07  00 00 00 76 61 6c 6f 72  |...........valor|
00000050  5f 31 07 00 00 00 76 61  6c 6f 72 5f 32 07 00 00  |_1....valor_2...|
00000060  00 76 61 6c 6f 72 5f 33  15 02 19 3c 15 00 38 06  |.valor_3...<..8.|
00000070  73 63 68 65 6d 61 15 04  00 15 0c 38 03 6b 65 79  |schema.....8.key|
00000080  15 00 00 15 0c 38 06 76  61 6c 75 65 73 15 00 00  |.....8.values...|
00000090  16 06 19 1c 19 2c 26 08  1c 15 0c 19 17 00 19 18  |.....,&.........|
000000a0  03 6b 65 79 15 00 16 06  16 64 16 64 26 08 3c 36  |.key.....d.d&.<6|
000000b0  00 00 00 00 26 6c 1c 15  0c 19 17 00 19 18 06 76  |....&l.........v|
000000c0  61 6c 75 65 73 15 00 16  06 16 64 16 64 26 6c 3c  |alues.....d.d&l<|
000000d0  36 00 00 00 00 16 c8 01  16 06 00 00 74 00 00 00  |6...........t...|
000000e0  50 41 52 31                                       |PAR1|
000000e4

No começo e no final do arquivo, temos os “magic bytes”, a constante PAR1 que identifica o arquivo como sendo um parquet.

O arquivo é mais simples que o gerado pelo fastparquet, mas não não está totalmente funcional: consegui ler com a implementação padrão em Java e Arrow, mas não usando Spark e nem o próprio fastparquet.

A implementação completa desse script está nesse arquivo.

É isso? Mais ou menos

Imagino que para resolver o problema de compatibilidade, seja necessário preencher mais metadados, que algumas implementações tratam como obrigatória. Meu objetivo era entender melhor o formato, então essa implementação capenga já atendeu seu objetivo, não animei de ir atrás de resolver essa questão.

No futuro, mais interessante que fazer uma implementação completa, seria entender os impactos de diferentes estratégias para gerar um arquivo. Um arquivo parquet – contendo os mesmos dados – pode ser gerado de diferentes formas:

• Eu usei o encoding básico, mas estratégias de dictionary encoding e delta encoding podem fazer uma enorme diferença, além da compactação pura e simples.

• Como funcionam o Page Index? É possível ter uma boa performance de look-up para acessos baseados em linha?

• Qual o tamanho ideal de páginas e grupos de linha? Discute-se muito o problema de “small files” em Big Data, mas nunca vi essa discussão para a estrutura interna dos arquivos.

• Qual as diferenças entre as várias implementações? São relevantes?

Talvez, em um post futuro, eu explore essa questão das diferentes implementações e estratégias para gerar arquivos parquet.

Por outro lado, programadores costumam tratar com desdém a ideia de low-code. Muitas vezes por simples elitismo e protecionismo, mas também por experiências terríves: soluções desnecessariamente complexas, “lock-in” em plataformas proprietárias, dificuldades de operação e manutenção.

Entre os fatores para o sucesso ou fracasso, entendo que passe muito pela complexidade acidental e essencial do problema. Low-code funciona muita bem para problemas com baixa complexidade essencial, mas pode virar um caos para problemas de negócio complexos.

Complexidade essencial e acidental

A complexidade acidental são questões “técnicas”, aspectos do problema que os engenheiros devem saber lidar e são inerentes ao desenvolvimento da solução. Por exemplo, como escolher o banco de dados ideal, que se adequa ao problema e atenda aos requisitos funcionais e não-funcionais.

A complexidade essencial se refere ao problema de negócio. Se precisamos implementar um sistema de tributação, não podemos mexer nos requisitos para simplificar o código.

Um boa solução de software lida com a complexidade essencial, adicionando o mínimo possível de complexidade acidental.

Não é uma tarefa fácil, mesmo com bons engenheiros e ferramentas, é comum acabar com mais complexidade que o necessário. Quando a solução fica a cargo de alguém não especializado, usando ferramentas limitadas, a situação tende a ficar muito pior.

Por isso, o quanto uma solução low-code faz sentido, depende muito da complexidade essencial. Não é uma relação linear, a complexidade acidental tende a crescer muito mais em função da complexidade essencial.

O cenário do caos

Por natureza da especialidade, engenheiros são treinados para focar em complexidade acidental: é interessante discutir como montar uma linha do tempo em baixa latências para milhões de usuários, mas nem tanto em entender todas as regras de cobrança do ICMS.

Suponha que existe um processo para estimar valor dos impostos, consumindo arquivos tabulares e gerando outro, para relatório e acompanhamento. Esse tipo de cenário, normalmente é visto como o ideal para low-code: os contadores conseguem implementar e validar de forma autônonoma, as demandas de latência são mínimas e não é operacional.

Depois de algum tempo, temos o seguinte cenário:

• A ferramenta low-code depende de várias outras, que também não são adequadas mas resolvem outras limitações, como planilhas Excel e/ou scripts Python locais.

• Poucas pessoas conseguem entender a solução, porque é uma ferramenta proprietária e a lógica é representada como um diagrama incompreensível.

• O custo de migrar a solução para um sistema é muito alto (e ninguém quer fazer), é preciso pagar e sustentar indefinidamente a solução.

• O relatório também está sendo usado de forma operacional, porque é a melhor fonte dessa informação.

A natureza do problema

O problema desse cenário hipotético, foi desconsiderar a complexidade essencial do problema. Um fluxo com arquitetura de solução simular, mas uma lógica de negócios simples, seria um bom caso de uso para low-code.

Em um cenário de lógica complexa, o ideal seria um programador competente, para desenvolver um código sustentável. Apesar de ser uma arquitetura simples, as regras podem demandar muito código e abstrações sofisticadas, cenário em que ferramentas low-code não são o ideal.

Muito dos esforços na engenharia de software, estão relacionados a lidar esse tipo de problema, por exemplo:

• A consolidação da programação orientada a objetos e mantras como SOLID e DRY, foi pelo anseio de melhor organização e abstração;

• o uso de ferramentas e estratégias de versionamento é fundamental em cenários de alta complexidade e colaboração;

• um dos atrativos da arquitetura de micro-serviços, é conseguir distribuir a complexidade essencial por múltiplos sistemas.

O melhor jeito de atuar usando as melhores práticas, é usando linguagens de programação e plataformas modernas.

Usando “bad-code” no lugar

Nem sempre é viável ter especialistas, para fazer desenhar e contruir a solução usandos as melhores ferramentas. Uma alternativa que não resolve, mas pode mitigar alguns problemas, é considerar o uso de soluções em código desenvolvida por quem não é especialista.

Posso estar errado – realmente não sou o melhor para opinar, dado que programo há muito tempo – mas entendo que o problema do usuário de low-code não é sobre aprender a programar.

Na área de dados, é muito comum ter pessoas que sabem programar bem, mas que não estão familiarizadas com processos de tecnologia e boas práticas. Inclusive, a ideia de usar soluções low-code, muitas vezes é para substituir códigos ruins de VBA ou em linguagens como PL/SQL e Transact-SQL.

Fazer um notebook linguição usando Python não é necessariamente melhor, reproduz os mesmos erros em outra tecnologia. A questão é facilitar uma possível evolução, para algo mais estruturado e sustentável.

Por exemplo, pode-se criar um ambiente restrito para implantar essas soluções, usar uma imagem com Python instalado e as bibliotecas básicas. Mesmo que seja necessário uma re-escrita completa do código no futuro, esse processo costuma ser bem menos doloroso usando a mesma plataforma, que migrando de outra.

Acertando o problema

Não acho low-code uma ideia terrível, mas não muito boa também: resolve uma classe de problemas, mas as promessas são irreais. A ideia de abolir código não é nova, há 20 anos tinha-se a ideia de gerar código a partir de UML e ferramentas WYSIWYG para construir sites. Por que elas não se tornaram o padrão?

Grandes empresas – as consumidoras dessas ferramentas – são cheias de complexidade essencial, que são difíceis de implementar em código e pior ainda em ferramentas low-code. É importante identificar, se o problema a ser resolvido tem esse tipo complexidade, pois há o risco da solução virar mais um problema.

Entendo que muito disso, passa pelos profissionais de tecnologia, especialmente na etapa de arquitetura de solução. Somos ensinados a lidar com complexidade acidental, pecando mais por excesso que falta de precaução. Por outro lado, a complexidade essencial acaba aparecendo apenas no final ou no meio da execução do projeto, porque é normal abstrair o problema nessa etapa.

Em resumo: uma arquitetura simples não significa um código simples, nenhuma ferramenta resolverá complexidade essencial, subestimá-la é um erro recorrente que precisamos nos atentar.