Tabela de Consulta em Python

Uma tabela de consulta armazena valores para que o código possa recuperá-los usando uma chave ou posição. Ela é útil quando a mesma relação é consultada repetidamente, como ao associar códigos de produtos a preços. Pré-calcular um resultado pode evitar a repetição de um cálculo, mas a tabela ocupa memória e precisa ser atualizada quando os dados de origem mudam.

Escolha a estrutura de acordo com o formato das chaves e o trabalho que você precisa realizar: dicionários aceitam chaves hasháveis arbitrárias, listas e arrays usam posições inteiras, e um DataFrame oferece colunas rotuladas e operações tabulares. Os exemplos a seguir mostram como cada estrutura realiza uma consulta prática.

Escolha uma estrutura de tabela de consulta para seus dados

Primeiro, pergunte o que identifica um valor. Use um dicionário para nomes, códigos ou outras chaves que não sejam posições inteiras densas. Use uma lista quando as posições forem números inteiros consecutivos a partir de zero e os valores puderem ser armazenados em uma sequência do Python. Use um array NumPy quando os dados forem numéricos e as operações com arrays forem importantes. Use um DataFrame do Pandas quando cada registro tiver vários campos nomeados ou quando você precisar filtrar dados e realizar outras operações tabulares. NumPy e Pandas são dependências de terceiros; instale-os no ambiente do seu projeto antes de usar os exemplos.

Use um dicionário para consultas por chave

Um dicionário associa cada chave distinta e hashável a um valor. Ele funciona bem com chaves não sequenciais e permite definir explicitamente um valor alternativo com get. Para uma chave ausente, get retorna o valor padrão fornecido; o acesso com colchetes, por sua vez, gera KeyError quando a chave não existe.

Execute este exemplo:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

prices = {"tea": 2.5, "coffee": 3.0, "cocoa": 2.75}
print(prices["tea"])
print(prices.get("juice", "not listed"))

2.5
not listed

A consulta em um dicionário tem complexidade média O(1), o que não é uma garantia para todas as cargas de trabalho. As chaves precisam ser hasháveis, e atribuir um valor a uma chave existente substitui o valor anterior. Se os registros de origem mudarem, atualize também o dicionário para evitar que a consulta retorne dados desatualizados.

Use uma lista para índices inteiros densos

Uma lista é uma tabela simples quando os índices válidos são densos e começam em zero: o índice i corresponde ao (i + 1)º item. Ela não é adequada para identificadores esparsos, como números de clientes, pois as lacunas exigiriam posições sem uso ou um mapeamento separado. O acesso por índice tem complexidade O(1); os valores continuam sendo objetos comuns do Python.

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

labels = ["bronze", "silver", "gold"]

def label_for(index):
    if 0 <= index < len(labels):
        return labels[index]
    return "index out of range"

print(label_for(2))
print(label_for(5))

gold
index out of range

A verificação explícita do intervalo trata tanto índices menores que zero quanto índices iguais ou maiores que o tamanho da lista. Listas do Python também aceitam índices negativos, que contam de trás para a frente a partir do fim. Portanto, valide o índice primeiro quando as chaves da tabela forem definidas apenas como posições não negativas.

Use um array NumPy para dados numéricos

Um array NumPy é útil quando a tabela contém valores numéricos e você também precisa de cálculos vetorizados, fatiamento ou outras operações com arrays. Instale NumPy separadamente; ele não faz parte da biblioteca padrão do Python. Uma consulta de um único valor continua sendo apenas um acesso por índice, portanto um array não substitui automaticamente um dicionário com mais velocidade.

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

import numpy as np

rates = np.array([1.0, 1.5, 2.0, 2.5])
index = 2
if 0 <= index < len(rates):
    print(rates[index])
else:
    print("index out of range")
print((rates * 2).tolist())

2.0
[2.0, 3.0, 4.0, 5.0]

A verificação dos limites é útil quando o índice vem de uma entrada externa. Em geral, arrays NumPy usam um único tipo de elemento, o que pode facilitar operações numéricas. Escolha o tipo e o formato do array de acordo com os dados que precisa armazenar.

Use um DataFrame do Pandas para dados tabulares

Um DataFrame é adequado para registros com colunas nomeadas, especialmente quando a consulta faz parte de uma tarefa maior de filtragem ou análise. Instale Pandas separadamente. Filtrar por uma coluna compara as linhas e retorna um DataFrame quando você seleciona apenas linhas. Na expressão abaixo, selecionar a única coluna price com .loc retorna uma Series; o filtro pode percorrer as linhas. Para consultas repetidas por chave, considere definir um índice significativo e usar .loc.

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

import pandas as pd

items = pd.DataFrame({
    "code": ["A", "B", "C"],
    "price": [1.25, 2.50, 3.75],
})
match = items.loc[items["code"] == "B", "price"]
if not match.empty:
    print(match.iloc[0])
else:
    print("not found")

2.5

Esse padrão trata a ausência de um código correspondente sem tentar acessar por índice um resultado vazio. Se os códigos forem únicos e consultados repetidamente, items.set_index("code").loc["B", "price"] expressa uma consulta por rótulo; confirme que o código existe antes de acessá-lo e decida como lidar com rótulos duplicados.

Trate chaves ausentes e índices inválidos

Escolha uma política para valores ausentes que seja adequada a quem chama a função. dict.get(key, default) retorna um valor alternativo, enquanto key in mapping permite distinguir a ausência de uma chave de um valor armazenado que por acaso seja igual ao padrão. Use try/except KeyError quando a ausência da chave for excepcional na lógica ao redor. Para listas e arrays, valide o índice com 0 <= index < len(table) se posições negativas não devem contar a partir do fim. Para um filtro de DataFrame, verifique se o resultado está vazio antes de selecionar a primeira linha. Mantenha a política consistente entre as funções para que quem as utiliza saiba se a ausência retorna um valor sentinela, um padrão ou um erro.

Compare o desempenho e as vantagens e limitações práticas

A consulta por chave em um dicionário tem complexidade média O(1), enquanto uma lista ou um array unidimensional leva O(1) para acessar uma posição. Em geral, um filtro booleano de DataFrame tem complexidade O(n), pois testa as linhas; um índice pode permitir acesso por rótulo, mas o custo e o comportamento dependem da criação do índice e do formato dos dados. Essas descrições de complexidade não permitem prever o tempo real para qualquer tamanho de entrada: os custos de preparação, os tipos de chave, a organização dos dados, as operações da biblioteca e o uso de memória também importam.

Use a estrutura mais simples que corresponda às chaves e às operações necessárias: dicionário para chaves arbitrárias, lista para posições densas, array NumPy para operações numéricas com arrays e DataFrame para dados tabulares com rótulos. Se o desempenho for decisivo, compare as opções com dados representativos. Considere também a memória: dicionários armazenam associações entre chaves e valores, listas contêm referências a objetos do Python e arrays NumPy armazenam elementos tipados; o uso real depende dos dados e da implementação. Se a tabela de consulta for derivada de dados de origem que podem mudar, recrie-a ou atualize-a sempre que esses dados mudarem para evitar respostas desatualizadas.