Ler e gravar dados no pandas: carregamento e armazenamento

Um arquivo CSV é texto simples organizado em registros e campos. Vírgulas geralmente separam os campos, e o primeiro registro costuma fornecer os nomes das colunas. O arquivo contém caracteres, não um esquema do pandas, por isso lê-lo também significa decidir o que esses caracteres representam.

Carregue e inspecione um arquivo pequeno

Suponha que um arquivo contenha:

order_id,date,region,units,price
1001,2026-03-02,North,3,4.50
1002,2026-03-02,South,1,12.00
1003,2026-03-03,North,2,7.25

Leia-o e inspecione o resultado:

import pandas as pd

df = pd.read_csv("sales.csv")
print(df.head())
print(df.shape)
print(df.dtypes)
df.info()

A forma é (3, 5): três linhas de dados e cinco colunas. O pandas infere int64 para order_id e units e float64 para price. A coluna date ainda contém texto. No pandas 3, colunas de texto inferidas normalmente mostram str; versões mais antigas do pandas frequentemente mostram object.

Cada inspeção responde a uma pergunta diferente. head() mostra se os campos estão alinhados aos rótulos. shape revela linhas ausentes ou uma coluna adicional inesperada. dtypes verifica a interpretação, e info() acrescenta contagens de valores não nulos. Uma coluna destinada a números que é carregada como texto merece uma análise dos valores brutos: uma unidade, um marcador ou uma convenção decimal diferente pode impedir a inferência numérica.

Associe rótulos aos registros

Para um arquivo sem cabeçalho cuja primeira linha é 1001,North,3, use:

df = pd.read_csv(
    "orders.txt",
    header=None,
    names=["id", "region", "units"]
)

Sem essa escolha, o pandas usa o primeiro registro como cabeçalho. Os valores desse registro tornam-se nomes de colunas e ele desaparece dos dados. Use index_col="order_id" quando uma coluna existente deve rotular as linhas. Use usecols=["region", "units"] para ler apenas essas colunas ou nrows=1000 para inspecionar as primeiras 1.000 linhas de dados antes de carregar um arquivo grande.

Deixe o leitor de CSV tratar as aspas

O registro "Smith, Jane",Boston,10 tem três campos. A vírgula dentro do nome entre aspas pertence ao nome. Duas aspas duplas dentro de um campo entre aspas representam uma aspa dupla literal: "O'Neil ""Red""" torna-se O'Neil "Red". Um campo entre aspas pode até conter uma quebra de linha, por isso registros e linhas físicas nem sempre correspondem.

Chamar line.split(",") divide o nome e não consegue tratar essas regras. read_csv as trata durante a análise sintática. pd.read_table usa tabulação como separador padrão; pd.read_fwf trata campos definidos por posições de caracteres.

Encontre o arquivo que o Python procura

Um caminho relativo é resolvido a partir do diretório de trabalho atual do programa. Se "data/sales.csv" não for encontrado, inspecione o diretório com Path.cwd() após from pathlib import Path. Um caminho absoluto, um objeto Path, uma URL ou um arquivo de texto em memória como StringIO também pode ser passado a read_csv. Verifique a localização antes de alterar opções de análise: um arquivo ausente e um arquivo interpretado incorretamente são problemas diferentes.

Um delimitador separa campos; um separador decimal separa as partes inteira e fracionária de um número. Um separador de milhares agrupa algarismos. Essas três funções precisam de configurações distintas, mesmo quando o mesmo símbolo é usado para funções diferentes em arquivos diferentes.

Inspecione os caracteres antes de escolher as opções

Examine algumas linhas brutas em um editor. Uma extensão .csv não garante o uso de vírgulas, e .txt não identifica uma estrutura. Configurações comuns são:

Você pode inspecionar o início sem ler o arquivo inteiro:

with open("products.csv", encoding="utf-8") as f:
    print(f.readline())
    print(f.readline())

Analise uma exportação regional

Considere este texto:

product;price;qty
Tea;3,50;1.200
Coffee;12,90;850

Os pontos e vírgulas dividem os campos, a vírgula é o separador decimal e o ponto agrupa milhares. Informe explicitamente as três convenções na leitura:

df = pd.read_csv(
    "products.csv",
    sep=";",
    decimal=",",
    thousands="."
)

Os preços tornam-se 3,5 e 12,9. As quantidades tornam-se 1.200 e 850. Com o separador padrão por vírgula, esse cabeçalho não descreve três colunas separadas por vírgulas. Mesmo depois de escolher sep=";", o trabalho não está concluído: os preços permanecem como texto e "1.200" pode tornar-se o número decimal 1,2. Esse último resultado é um número válido com o significado errado, por isso um erro grave pode ocorrer sem uma exceção de análise.

Compare alguns valores carregados com o texto de origem e inspecione describe() para detectar intervalos pouco plausíveis. Uma quantidade esperada na casa dos milhares que aparece próxima de um indica um possível problema de convenção numérica. Alterar apenas o delimitador não corrigirá isso.

Distinga limites de campos de agrupamento de números

Em um arquivo delimitado por vírgulas, um número agrupado como "1,234.50" deve ficar entre aspas. A vírgula interna faz parte do número. Com thousands=",", o pandas pode ler o campo entre aspas como 1.234,5. Sem aspas, a vírgula também cria um limite de campo; thousands não consegue restaurar a estrutura perdida do registro.

Escolha um mecanismo de análise compatível

O mecanismo C padrão trata estruturas comuns rapidamente. O mecanismo Python oferece detecção de separador com sep=None, separadores expressos como expressões regulares e skipfooter. A detecção examina uma amostra e pode escolher incorretamente em um relatório irregular, por isso informe diretamente um separador conhecido.

Um separador com mais de um caractere geralmente é tratado como expressão regular e exige o mecanismo Python; r"\s+" é um caso especial também aceito pelo mecanismo C. O mecanismo PyArrow pode ler com threads paralelas, mas oferece suporte a um conjunto diferente de opções. Por exemplo, chunksize não é aceito com engine="pyarrow". Escolha o mecanismo conforme as opções necessárias ao arquivo e depois confira a estrutura e os valores do resultado.

A inferência de tipo não pode saber se 999 é uma medida ou um código para um valor desconhecido. Ela também não pode saber se zeros à esquerda têm significado. Use as definições dos dados para configurar as opções de leitura antes que a inferência altere esses valores.

Declare marcadores de valores ausentes onde se aplicam

O pandas reconhece campos vazios e marcadores internos como "NA", "N/A", "n/a", "NULL", "NaN" e "None". Uma fonte pode usar marcadores adicionais. Suponha que score contenha 88, "n/a", "-" e 999, com 999 definido como desconhecido:

df = pd.read_csv(
    "scores.csv",
    na_values={"score": ["-", "999"]}
)

A coluna de pontuação agora contém 88,0 e três valores ausentes. Sem declarar os marcadores, "-" pode fazer a coluna permanecer como texto; um valor sentinela numérico não declarado pode entrar nos cálculos. A média de 88 e 999 é 543,5, embora a única pontuação conhecida seja 88.

Um dicionário restringe um marcador à coluna indicada. Uma opção na_values=["999"] para o arquivo inteiro também removeria um código de produto real 999. Se "NA" for um rótulo real, use keep_default_na=False para desativar a lista interna de marcadores e liste explicitamente os marcadores que de fato significam ausência. Com essa configuração, inclua "" se campos vazios ainda precisarem ser considerados ausentes.

Preserve valores de acordo com sua função

Leia identificadores como texto:

df = pd.read_csv(
    "visits.csv",
    dtype={"site_code": str, "visits": "Int64"}
)

Um código como "00501" deve continuar com cinco caracteres. Lê-lo como inteiro produz 501; converter esse inteiro para texto depois produz "501", não o código original. Use um tipo numérico para valores usados em cálculos.

Colunas comuns de inteiros do NumPy não podem conter NaN, por isso uma coluna de contagem com uma lacuna frequentemente se torna float64. O tipo "Int64" do pandas, com I maiúsculo e suporte a valores ausentes, mantém valores inteiros e representa uma lacuna com <NA>. dtype_backend="numpy_nullable" solicita tipos com suporte a valores ausentes em todo o resultado. Para um pequeno conjunto de rótulos repetidos, dtype={"region": "category"} armazena os rótulos como categorias e pode reduzir o uso de memória.

Especifique como as datas são escritas

Texto que parece uma data permanece como texto até ser interpretado. Para datas com dia primeiro, como "03/04/2026" e "13/04/2026", use:

df = pd.read_csv(
    "events.csv",
    parse_dates=["day"],
    date_format="%d/%m/%Y"
)

Esses valores tornam-se 3 de abril e 13 de abril. Sem um formato, uma inferência com mês primeiro pode trocar dias e meses válidos ou deixar de converter a coluna. dayfirst=True expressa uma preferência; um formato explícito declara a estrutura esperada. Datas ISO como "2026-04-03" evitam a ambiguidade entre dia e mês.

Após a leitura, inspecione dtypes, isna().sum() e a contagem de linhas. Verifique uma data cuja interpretação diferencie as convenções. Uma coluna que ainda aparece como texto indica que a interpretação não produziu os valores de data e hora desejados; uma contagem de ausentes que aumenta inesperadamente pode revelar um rótulo real confundido com um marcador.

Um relatório pode misturar uma tabela com títulos, linhas em branco, comentários, totais e notas sobre a fonte. Primeiro localize o cabeçalho e os limites dos dados. Caso contrário, um leitor pode confundir um título com nomes de colunas ou incluir um total como observação comum.

Leia apenas a tabela

Um relatório contém estas nove linhas físicas:

Monthly sales report
Exported 2026-04-01

region,jan,feb
North,120,135
# test row below
South,98,101
Total,218,236
Source: internal system

As três primeiras linhas precedem o cabeçalho. As duas últimas não são observações. Leia o relatório com:

df = pd.read_csv(
    "report.csv",
    skiprows=3,
    comment="#",
    skipfooter=2,
    engine="python"
)

O resultado tem duas linhas. Janeiro totaliza 218 a partir de North e South. Manter a linha de total acrescentaria outros 218 e resultaria em 436. Com as opções padrão, o título de um campo pode, em vez disso, tornar-se o cabeçalho e causar um erro de análise quando chegarem registros de três campos.

skiprows=3 conta as três primeiras linhas físicas, incluindo a linha em branco. Uma lista como skiprows=[0, 2] remove posições específicas de linhas contadas a partir de zero. Linhas em branco são ignoradas por padrão, e comment="#" remove o texto de comentários. skipfooter precisa do mecanismo Python. Ajuste essas configurações à estrutura real; uma contagem fixa de linhas a ignorar pode deixar de estar correta quando um programa de exportação adiciona uma linha de título.

Investigue registros malformados

Um registro com campos demais pode acionar on_bad_lines="error", a opção padrão. "warn" o ignora com um aviso, enquanto "skip" o remove sem aviso. Antes de escolher qualquer uma das duas opções, inspecione o registro bruto. Uma vírgula sem aspas dentro de um nome ou um delimitador incorreto pode criar campos adicionais; ignorar o registro nesse caso causa a perda de uma observação válida em vez de corrigir a causa.

Poucos campos têm um comportamento diferente. Sob id,name,score, o registro 2,Ben é carregado com uma pontuação ausente. Isso pode não gerar erro. Confira as contagens de valores ausentes e de linhas e compare os registros mantidos com a fonte ao excluir linhas malformadas.

Leia cabeçalhos em várias linhas ou posições de caracteres

Duas linhas de rótulos de colunas podem formar um índice hierárquico (MultiIndex). Com os rótulos de grupos region,sales,sales acima de ,2025,2026, header=[0, 1] produz rótulos como ("sales", "2025"). Se rótulos sem hierarquia forem mais adequados à análise, ignore as duas linhas de cabeçalho e forneça names=["region", "sales_2025", "sales_2026"].

Texto de largura fixa não tem delimitador. Os limites das colunas são posições de caracteres:

df = pd.read_fwf(
    "readings.txt",
    colspecs=[(0, 4), (4, 11), (11, 16)]
)

Esses intervalos semiabertos incluem cada início e excluem cada fim. O primeiro campo ocupa as posições de 0 a 3, e o próximo começa em 4. widths=[4, 7, 5] descreve a mesma estrutura. A inferência é conveniente para amostras regulares; limites explícitos impedem que um valor curto no início defina uma largura incorreta.

Um arquivo armazena bytes, cada um com um valor de 0 a 255. Uma codificação define como os caracteres são representados por esses bytes. A codificação converte texto Python em bytes; a decodificação converte bytes novamente em texto. Os mesmos bytes podem representar caracteres diferentes segundo regras de decodificação diferentes.

Conte caracteres e bytes separadamente

text = "café"
raw = text.encode("utf-8")
print(len(text))  # 4 characters
print(len(raw))   # 5 bytes
print(raw.decode("utf-8"))  # café

O acento não forma um segundo caractere visível aqui. A letra "é" precisa de dois bytes em UTF-8, por isso quatro caracteres ocupam cinco bytes. Uma contagem de bytes e uma contagem de caracteres respondem a perguntas diferentes.

ASCII define 128 caracteres, incluindo letras básicas do alfabeto inglês, algarismos, pontuação e códigos de controle. Os valores de byte desses caracteres coincidem em ASCII, UTF-8, Latin-1 e Windows-1252. Essa parte inicial compartilhada explica por que uma amostra contendo apenas texto em inglês pode parecer correta mesmo quando a configuração de codificação está errada.

Reconheça as principais famílias de codificação

UTF-8 representa todos os caracteres Unicode e é a escolha habitual para troca de texto. Latin-1 e Windows-1252 representam um conjunto menor de caracteres. Elas coincidem em muitas letras acentuadas, mas diferem em parte da faixa de bytes: Windows-1252 usa o byte 0x80 para "€", onde Latin-1 tem um caractere de controle. Não são nomes intercambiáveis para uma mesma codificação.

Leia corretamente as marcas de ordem de bytes

Uma marca de ordem de bytes, ou BOM, é um marcador no início de alguns arquivos. UTF-16 pode começar com FF FE para a ordem little-endian ou FE FF para a ordem big-endian. encoding="utf-16" usa a BOM para selecionar a ordem. Sem uma BOM, especifique "utf-16-le" ou "utf-16-be" de acordo com a fonte.

Uma BOM UTF-8 é EF BB BF. open(..., encoding="utf-8-sig") do Python a remove durante a decodificação. O simples "utf-8" em open() a mantém como \ufeff, que pode inesperadamente tornar-se parte do nome do primeiro cabeçalho. O leitor de CSV do pandas também trata uma BOM UTF-8 inicial, mas escolher utf-8-sig deixa clara a convenção esperada do arquivo.

Informe a codificação explicitamente

with open("notes.txt", encoding="utf-8") as f:
    text = f.read()

O padrão de open() depende da versão do Python e do modo UTF-8. Python 3.11 a 3.14 pode usar a codificação das configurações regionais; Python 3.15 ativa o modo UTF-8 por padrão, com a opção de desativá-lo. Uma codificação explícita mantém o script vinculado ao formato real do arquivo em diferentes computadores. Ela também impede que o padrão de uma plataforma altere sem aviso a forma como os mesmos bytes são lidos.

Uma codificação errada pode falhar de forma explícita com UnicodeDecodeError ou produzir silenciosamente um texto aparentemente legível, mas sem sentido, chamado mojibake. Ambos os problemas começam com a interpretação dos bytes pela regra errada. Guarde o arquivo original para poder decodificá-lo novamente.

Diagnostique um erro a partir da fonte

Um CSV salvo em Windows-1252 contém nomes de cidades, incluindo "Zürich" e "Málaga". Lê-lo como UTF-8 pode falhar no byte 0xfc, usado para "ü" em Windows-1252. Quando as configurações de exportação da fonte confirmarem a codificação, leia-o com:

df = pd.read_csv("cities.csv", encoding="cp1252")
print(df["city"].head())

Inspecione nomes que contenham acentos ou símbolos. Uma amostra composta inteiramente de caracteres ASCII não consegue distinguir essas codificações. Um byte específico inválido em UTF-8 sugere uma possível codificação antiga; ele não identifica de forma única qual codificação antiga produziu o arquivo.

Reconheça um problema que não gerou erro

Bytes UTF-8 decodificados como Windows-1252 podem transformar "café" em "café" e "São Paulo" em "São Paulo". O leitor produziu caracteres sem falhar, mas são os caracteres errados. Leia os bytes originais novamente usando UTF-8:

df = pd.read_csv("cities.csv", encoding="utf-8")

A busca e substituição corrige um sintoma visível por vez e pode deixar passar outras letras danificadas. Ela também corre o risco de alterar uma ocorrência legítima de um caractere. A decodificação correta trata a causa em todo o arquivo.

Reúna evidências sobre a codificação

Comece pela documentação do fornecedor ou pelas configurações de exportação. Se necessário, inspecione uma pequena amostra de bytes:

with open("cities.csv", "rb") as f:
    sample = f.read(200)
print(sample)

O modo binário preserva os bytes sem decodificá-los. Uma BOM pode dar uma pista direta. Um detector como charset-normalizer estima uma codificação provável, mas uma amostra curta pode ser compatível com várias candidatas. Teste o resultado comparando nomes acentuados e símbolos conhecidos.

Latin-1 atribui um caractere a cada byte, por isso pode decodificar qualquer sequência de bytes sem erro. Esse sucesso, por si só, não indica se os caracteres estão corretos. Windows-1252 também usa caracteres de um byte, mas deixa alguns valores de byte indefinidos e pode gerar um erro de decodificação.

Evite descartar as evidências

encoding_errors="replace" substitui bytes que o decodificador não consegue ler por "�". encoding_errors="ignore" os remove. Essas opções podem ajudar a inspecionar uma entrada danificada, mas causam perda de informação e não devem substituir a busca pela codificação correta. Um nome alterado para "Zrich" pode impedir uma correspondência tanto quanto um texto visivelmente corrompido.

Na saída, UTF-8 lida com a maior variedade de caracteres. Alguns programas de planilha o identificam com mais confiabilidade quando há uma BOM:

df.to_csv("cities_export.csv", index=False, encoding="utf-8-sig")

Abra novamente o arquivo exportado no programa que o receberá e inspecione os mesmos valores acentuados. O objetivo é ter o texto correto nas duas pontas da troca.

O tamanho de um arquivo no disco não corresponde à memória necessária para carregá-lo. O pandas constrói arrays, índices e valores de texto na memória, e os tipos desses objetos afetam o espaço necessário. Meça com df.memory_usage(deep=True) ou df.info(memory_usage="deep") antes de decidir como carregar mais dados.

Reduza os dados carregados na memória

Leia colunas selecionadas com usecols, inspecione uma amostra inicial com nrows e escolha tipos adequados com dtype. Uma categoria pode armazenar nomes de regiões repetidos de forma compacta. float32 usa menos espaço que float64, mas oferece cerca de sete algarismos significativos, por isso escolha-o apenas quando essa precisão for adequada às medidas. Uma pequena prévia ajuda a identificar tipos; ela não comprova que todas as linhas posteriores seguem o mesmo padrão.

Processe blocos e mantenha um resultado pequeno

chunksize altera o valor retornado de um DataFrame para um iterador de DataFrames. Para obter um total e uma média:

total = 0.0
count = 0
with pd.read_csv(
    "measurements.csv",
    usecols=["amount"],
    chunksize=100_000
) as reader:
    for chunk in reader:
        total += chunk["amount"].sum()
        count += chunk["amount"].count()
mean = total / count if count else float("nan")

O laço mantém uma soma acumulada e uma contagem dos valores não ausentes. Cada bloco pode ser liberado após o uso. Reunir todos os blocos em uma lista e concatená-los depois recria a necessidade de memória para o conjunto inteiro; a leitura em blocos só economiza memória quando o processamento mantém um resultado reduzido ou grava as partes processadas.

Um arquivo de dez linhas lido com chunksize=4 produz partes de 4, 4 e 2 linhas. Para valores de 1 a 10 com regiões que se repetem na ordem N, S, E, some os totais regionais parciais para obter N 22, S 15 e E 18. O total combinado é 55.

Combine as quantidades corretas

Somas e contagens são adicionadas. Mínimos são combinados tomando-se o menor mínimo parcial; máximos são combinados tomando-se o maior máximo parcial. Médias precisam de pesos porque os blocos podem conter números diferentes de observações válidas.

Para os valores 1, 2 e 3 em um bloco e 10 em outro, as médias dos blocos são 2 e 10. A média dessas médias é 6, atribuindo ao bloco de um valor o mesmo peso do bloco de três valores. Some as somas e as contagens: o total 16 em quatro observações dá média 4. As medianas dos blocos não contêm informações suficientes para reconstruir uma mediana geral.

Leia arquivos comprimidos diretamente

read_csv normalmente infere a compressão a partir de extensões reconhecidas como .gz, .bz2, .zip, .xz e .zst. Ele descomprime durante a leitura:

with pd.read_csv("measurements.csv.gz", chunksize=100_000) as reader:
    for chunk in reader:
        print(len(chunk))

Um arquivo ZIP usado dessa forma deve conter exatamente um arquivo de dados. df.to_csv("out.csv.gz", index=False) grava CSV comprimido com gzip. A compressão reduz o espaço em disco e o tamanho da transferência; ela não elimina a memória usada pela tabela decodificada. Para análises repetidas, converter um conjunto de dados verificado para Parquet também evita reinterpretar o texto e restaura os tipos de colunas armazenados.

Uma pasta de trabalho do Excel pode conter várias planilhas, títulos e totais calculados. As células têm valores e tipos armazenados, além de formatação de exibição. Ler uma planilha significa localizar a tabela de dados e entender quais partes da pasta de trabalho se tornam valores do DataFrame.

Escolha a planilha e seus limites

df = pd.read_excel(
    "quarterly.xlsx",
    sheet_name="Q1",
    skiprows=2,
    usecols="A:C",
    nrows=2
)

Suponha que a linha 1 seja um título mesclado, a linha 2 esteja vazia, a linha 3 contenha region, date e sales, e as linhas 4 a 5 contenham as observações. skiprows=2 faz da linha 3 o cabeçalho; nrows=2 interrompe a leitura antes do total na linha 6. Para North 1.200 e South 950, as duas observações somam 2.150. Incluir um total armazenado em cache de 2.150 como terceira observação dobraria esse valor.

O Excel exibe números de linha a partir de 1; as posições de linha do pandas começam em 0. header=2 também seleciona a linha 3 do Excel como cabeçalho. usecols="A,C,E:F" seleciona colunas separadas e um intervalo. O padrão sheet_name=0 lê a primeira planilha; um nome seleciona uma planilha específica, e sheet_name=1 seleciona a segunda.

sheet_name=None retorna um dicionário que associa nomes de planilhas a DataFrames. Selecione uma chave ou percorra .items() em um laço; o próprio dicionário não é um DataFrame. Para várias leituras de uma pasta de trabalho:

with pd.ExcelFile("quarterly.xlsx") as xf:
    print(xf.sheet_names)
    q1 = pd.read_excel(xf, sheet_name="Q1")

Saiba o que a célula realmente armazena

Uma porcentagem exibida como "15%" armazena 0,15. Um número exibido com cinco algarismos pode armazenar 2.139, mesmo que a tela mostre "02139". Nenhuma opção de leitura pode recuperar um zero que existe apenas na formatação. Armazene identificadores como texto na pasta de trabalho e passe também dtype={"zip": str} durante a leitura; caso contrário, o pandas pode inferir inteiros mesmo em células de texto compostas apenas de algarismos.

A precisão numérica do Excel é limitada a 15 algarismos significativos. Um identificador de 16 algarismos inserido como número já pode estar danificado antes de o Python lê-lo. Armazene esses valores como texto. Uma planilha tem no máximo 1.048.576 linhas e 16.384 colunas, por isso um conjunto de dados muito grande precisa de outro formato.

Trate fórmulas e células mescladas com cuidado

O pandas não calcula fórmulas. Ele lê resultados armazenados em cache na pasta de trabalho. Um aplicativo de planilha pode salvar resultados atuais; um arquivo gerado por script pode ter resultados em cache ausentes, provisórios ou desatualizados. O openpyxl não calcula um resultado, e o XlsxWriter normalmente grava zero como valor provisório, a menos que outro seja fornecido. Recalcule valores importantes no pandas ou abra e salve a pasta de trabalho em um programa de planilha antes de confiar nos totais armazenados em cache.

Apenas a célula superior esquerda de um intervalo mesclado armazena o rótulo. Um rótulo de país mesclado pode, portanto, deixar células vazias nas linhas abaixo. Quando a estrutura confirmar que o rótulo se aplica a essas linhas, df["country"] = df["country"].ffill() o propaga para baixo. Inspecione o limite da tabela antes de preencher.

A leitura exige uma biblioteca de mecanismo. O openpyxl trata .xlsx e .xlsm; xlrd trata .xls, pyxlsb trata .xlsb, odf trata .ods e calamine oferece suporte a vários formatos de planilha. Um mecanismo ausente gera um ImportError que informa a dependência necessária. Cores, comentários e outros estilos da estrutura não são carregados como dados do DataFrame.

O Excel é útil quando pessoas precisam abrir e inspecionar um relatório em um programa de planilha. Um DataFrame pode tornar-se uma planilha, ou vários DataFrames podem compartilhar uma pasta de trabalho. Escolha o caminho de destino e os nomes das planilhas antes de gravar, para que cada tabela vá para o lugar desejado.

Grave uma ou várias tabelas

weather.to_excel(
    "weather.xlsx",
    sheet_name="Weather",
    index=False
)

index=False mantém os números de linha padrão fora da planilha. Sem essa opção, eles aparecem como uma primeira coluna adicional e podem retornar como "Unnamed: 0" em uma leitura posterior. Mantenha um índice apenas quando ele contiver rótulos significativos que devam fazer parte do relatório.

Uma chamada de to_excel com caminho grava uma pasta de trabalho nesse caminho, substituindo um arquivo existente. Chamá-la uma vez para Weather e outra para Counts no mesmo caminho pode deixar apenas a segunda tabela. Use um único objeto de gravação para ambas:

with pd.ExcelWriter("report.xlsx") as writer:
    weather.to_excel(writer, sheet_name="Weather", index=False)
    counts.to_excel(writer, sheet_name="Counts", index=False)

O gerenciador de contexto fecha e finaliza a pasta de trabalho quando o bloco termina. Lê-la com pd.read_excel("report.xlsx", sheet_name=None) retorna um dicionário que contém os nomes das duas planilhas. Gravar .xlsx exige openpyxl ou XlsxWriter.

Atualize uma planilha em uma pasta de trabalho existente

Para preservar outras planilhas enquanto substitui uma delas, use um objeto de gravação em modo de acréscimo:

with pd.ExcelWriter(
    "report.xlsx",
    mode="a",
    engine="openpyxl",
    if_sheet_exists="replace"
) as writer:
    counts.to_excel(writer, sheet_name="Counts", index=False)

if_sheet_exists controla um conflito de nomes. "error" interrompe a operação, "new" cria outra planilha, "replace" substitui a planilha e "overlay" grava nas células existentes. A sobreposição não limpa células antigas fora da nova tabela, por isso uma atualização menor pode deixar linhas antigas para trás. Decida se o relatório precisa de uma substituição completa da planilha ou de uma sobreposição posicionada com cuidado.

Facilite a reabertura da saída

Nomes de planilhas têm limite de 31 caracteres e não podem conter :, \, /, ?, *, [ ou ]. Um nome curto como "Q1 Summary" funciona; "Q1/Q2" contém uma barra proibida. Alguns mecanismos emitem um aviso em vez de interromper a operação quando o nome é longo demais, por isso escolha nomes compatíveis.

startrow e startcol posicionam uma tabela usando deslocamentos contados a partir de zero. na_rep fornece um marcador visível para valores ausentes. float_format="%.2f" arredonda os números gravados, e autofilter=True adiciona botões de filtro ao cabeçalho no pandas 3. Colunas de data e hora são gravadas como datas do Excel.

Arredondar na saída altera os números armazenados, não apenas sua exibição. Mantenha separadamente um arquivo de análise com precisão completa quando um relatório arredondado for necessário. Abra novamente a pasta de trabalho e confira a lista de planilhas, as dimensões das tabelas e valores representativos. A leitura do Excel é relativamente lenta e um ciclo de gravação e leitura pode alterar os tipos de dados do pandas, por isso use Parquet para tabelas intermediárias de análise quando preservar os tipos for importante.

JSON armazena dados aninhados como texto. Objetos contêm pares de nome e valor, arrays contêm valores ordenados e strings usam aspas duplas. Seus outros valores são números, true, false e null. O módulo json do Python converte essa sintaxe em objetos Python antes de você construir uma tabela.

Interprete e grave JSON válido

import json

text = '{"station":"Oslo","active":true,"temp_c":[3.5,null,4.0]}'
data = json.loads(text)
print(data["active"])   # True
print(data["temp_c"])   # [3.5, None, 4.0]

Objetos tornam-se dicionários, arrays tornam-se listas e null torna-se None. json.loads interpreta uma string; json.load lê um arquivo aberto. As funções de gravação fazem o caminho inverso: json.dumps retorna texto e json.dump grava em um arquivo.

with open("station.json", "w", encoding="utf-8") as f:
    json.dump(data, f, ensure_ascii=False, indent=2)

ensure_ascii=False mantém legíveis caracteres como "ü". O padrão pode gravar o mesmo caractere como \u00fc; ambas as formas representam a mesma string. Um dicionário Python impresso não é JSON: aspas simples, True, None e vírgulas finais são inválidos na sintaxe JSON. O JSON padrão também não tem NaN. O codificador do Python o permite por padrão, mas allow_nan=False o rejeita; o pandas grava valores ausentes como null.

Use a organização adequada da tabela

Uma tabela JSON precisa de uma orientação, isto é, a disposição de linhas, rótulos e valores. orient="records" fornece um objeto por linha:

[{"city":"Lyon","temp_c":21.5},{"city":"Osaka","temp_c":null}]

A orientação padrão de DataFrame, "columns", agrupa valores sob nomes de colunas e depois sob rótulos de linhas. "split" armazena colunas, índice e dados separadamente. Especifique uma orientação compatível com o programa que receberá os dados, em vez de presumir que toda tabela JSON tem a mesma estrutura.

from io import StringIO
import pandas as pd

df = pd.read_json(
    StringIO('[{"code":"0042","amount":9.5}]'),
    orient="records",
    dtype={"code": str}
)

No pandas 3, uma string simples passada a read_json é um caminho, por isso envolva o texto JSON propriamente dito em StringIO. Mesmo strings JSON compostas apenas por algarismos podem ser inferidas como números; o tipo de dados explícito preserva "0042".

Use JSON Lines para registros sequenciais

JSON Lines tem um objeto JSON completo por linha, sem um array ao redor ou vírgulas entre registros:

{"id":1,"amount":9.5}
{"id":2,"amount":12.0}

Leia com pd.read_json(path, lines=True) e grave com df.to_json(path, orient="records", lines=True). As opções chunksize e nrows do leitor exigem lines=True, que disponibiliza os registros individuais sequencialmente.

Ao exportar datas, defina date_format="iso" para obter marcas temporais ISO legíveis. O pandas 3.1 ainda usa milissegundos desde a época Unix como padrão para a saída JSON comum de DataFrames, mas esse padrão está mudando. Uma saída explícita de datas evita depender de quem lê os dados para adivinhar o que um inteiro grande representa.

JSON aninhado pode descrever um pedido, o cliente desse pedido e vários itens em um único objeto. Antes de transformá-lo em tabela, decida a granularidade: o que uma linha representa. A granularidade determina quais valores podem ser somados.

Transforme primeiro os objetos aninhados

Considere dois pedidos. O pedido 501 pertence a Ana e tem os itens A1 (quantidade 2, preço 3,5) e B7 (quantidade 1, preço 10,0). O pedido 502 pertence a Ben e tem A1 (quantidade 4, preço 3,5). Os dados dos clientes são objetos aninhados e os itens são listas.

orders = [
    {"order_id": 501,
     "customer": {"name": "Ana", "country": "PT"},
     "items": [{"sku": "A1", "qty": 2, "price": 3.5},
               {"sku": "B7", "qty": 1, "price": 10.0}]},
    {"order_id": 502,
     "customer": {"name": "Ben", "country": "CA"},
     "items": [{"sku": "A1", "qty": 4, "price": 3.5}]}
]
order_rows = pd.json_normalize(orders)

Isso produz duas linhas e quatro colunas: order_id, items, customer.name e customer.country. Os campos aninhados de cliente tornam-se colunas com nomes separados por pontos. As listas de itens permanecem nas células; a normalização não transforma automaticamente toda lista em linhas.

Expanda uma lista com informações do objeto pai

items = pd.json_normalize(
    orders,
    record_path="items",
    meta=["order_id", ["customer", "name"]]
)

record_path escolhe a lista cujas entradas se tornam linhas. meta copia valores do objeto pai para cada linha, com uma lista de chaves para um caminho aninhado. O resultado tem três linhas de itens: duas para o pedido de Ana e uma para o de Ben. A receita é a quantidade multiplicada pelo preço: 7,0, 10,0 e 14,0, totalizando 31,0.

Se uma cobrança de frete no nível do pedido for 4,00, ela se repete nas duas linhas de itens do pedido 501. Somar essas cobranças repetidas resulta em 8,00 para um único pedido. Mantenha os valores relativos ao pedido em uma tabela separada de pedidos quando também precisar de uma tabela de itens; preserve order_id para conectá-las.

Controle nomes e campos ausentes

sep="_" cria nomes como customer_name. record_prefix="item_" distingue campos de itens de campos do objeto pai com o mesmo nome. max_level=0 mantém intactos os dicionários aninhados.

Um campo aninhado comum ausente de um registro torna-se ausente na coluna de saída correspondente. Um campo ausente solicitado por meta gera KeyError por padrão; errors="ignore" permite metadados ausentes e os preenche com NaN. Uma lista ausente indicada por record_path ainda precisa ser corrigida.

Retire os registros do objeto envoltório antes de transformá-los em tabela

Uma API pode retornar um objeto envoltório contendo count, next e results. Passe data["results"] a pd.json_normalize para transformar os registros em tabela. Passar o próprio objeto envoltório normaliza um único objeto, deixando a lista de resultados dentro de uma célula. Mantenha os metadados de paginação disponíveis para buscar páginas posteriores, mas construa a tabela de análise a partir da lista de registros propriamente dita.

Uma API da web aceita uma requisição HTTP em um ponto de acesso e retorna um código de status, cabeçalhos e um corpo. Muitas APIs usam corpos JSON, mas o recebimento de uma resposta não significa que ela contenha os dados ou todos os registros necessários.

Envie parâmetros e confira a resposta

import requests

resp = requests.get(
    url,
    params={"city": "Lima", "units": "metric"},
    timeout=10
)
resp.raise_for_status()
data = resp.json()
df = pd.json_normalize(data["results"])

Aqui, url é o ponto de acesso documentado da API. params codifica a string de consulta, de modo que espaços e caracteres especiais nos valores sejam tratados corretamente. A biblioteca requests não define tempo limite por padrão. Um único valor de tempo limite controla a espera pela conexão e pela leitura; ele não é um prazo para o download completo da resposta.

Chame raise_for_status() antes de usar o corpo. Esse método gera um erro HTTP para respostas 4xx e 5xx. Uma mensagem de erro em JSON pode ser interpretada sem falhas e ainda assim descrever uma requisição malsucedida; por outro lado, uma resposta 200 pode conter texto que não é JSON, fazendo resp.json() falhar. Inspecione resp.text quando o formato da resposta for inesperado.

Mantenha as credenciais separadas

Use o método de autenticação documentado pela API. Para um token de portador, leia uma chave de uma variável de ambiente e envie-a em um cabeçalho:

import os

key = os.environ["WEATHER_API_KEY"]
headers = {"Authorization": "Bearer " + key}

Mantenha chaves fora do código salvo e dos cadernos computacionais. Se uma chave tiver sido compartilhada ou registrada em um repositório, revogue-a e substitua-a. Uma chave concede acesso; ocultar um valor exibido posteriormente não desfaz sua exposição.

Continue até ler todas as páginas

Siga o mecanismo de próxima página documentado pela API, seja por números de página, deslocamentos ou uma URL para a próxima página. Reúna os registros de cada página e pare na condição final indicada. Um total de 230 registros com 100 por página exige páginas de 100, 100 e 30. A primeira página pode ser perfeitamente válida enquanto o conjunto de dados está incompleto.

Compare a contagem coletada com o total informado, quando disponível. Respeite os limites de requisições por período: 429 exige esperar antes de outra requisição, e Retry-After pode especificar a espera. Esse cabeçalho pode conter segundos ou uma data HTTP. Salve respostas brutas para obter uma análise reproduzível e evitar baixar os mesmos dados a cada nova execução.

Reconheça outros formatos de tabelas da web

pd.read_html(url) retorna uma lista de DataFrames, um para cada tabela HTML correspondente. match="Population" restringe as tabelas pelo texto que contêm. A função exige uma dependência de análise HTML, como lxml ou BeautifulSoup com html5lib. pd.read_xml lê elementos XML repetidos como linhas, usando lxml ou parser="etree". Consulte os termos de um site antes de extrair dados e prefira um download oficial ou uma API quando disponível.

Uma exportação CSV deve preservar os valores necessários ao destinatário e deixar claras suas convenções. Escolha se o índice das linhas é dado, como os valores ausentes aparecem e se a saída se destina a uma análise precisa ou a uma exibição arredondada.

Escolha o que se torna uma coluna

df.to_csv("weather_processed.csv", index=False)

O padrão é gravar o índice. Para uma tabela com índice numerado comum, isso adiciona um primeiro campo sem nome; uma chamada posterior de read_csv pode mostrá-lo como "Unnamed: 0". index=False deixa esses números de linha de fora. Quando o índice contiver rótulos significativos, mantenha-o e leia-o novamente com index_col=0.

Valores ausentes normalmente tornam-se campos vazios. na_rep="NA" torna-os visíveis, mas o leitor que receber o arquivo deve interpretar esse marcador corretamente. Em uma tabela de cidades com Lyon a 21,5 °C e Osaka a 18,25 °C, um valor ausente de chuva para Osaka deve permanecer distinto de chuva zero.

Adapte-se à convenção de texto do destinatário

df.to_csv(
    "weather_export.csv",
    index=False,
    sep=";",
    decimal=",",
    na_rep="NA",
    date_format="%Y-%m-%d",
    encoding="utf-8"
)

As opções de separador e decimal produzem valores como Lyon;21,5;0,0. A saída de datas ISO mantém dia e mês inequívocos. Use encoding="utf-8-sig" quando um programa de planilha que receberá o arquivo precisar de uma BOM para reconhecer UTF-8.

float_format="%.1f" grava uma casa decimal. O valor 18,25 torna-se "18.2" com essa formatação, e a precisão descartada não pode ser recuperada do CSV. Mantenha precisão completa para dados de análise; crie um relatório arredondado separado quando necessário.

Confira o que sobrevive a um ciclo de gravação e leitura

CSV armazena caracteres sem metadados dos tipos de dados do pandas. Considere quatro colunas: um identificador "02139", uma data e hora, uma categoria ordenada A < B < C e inteiros com suporte a valores ausentes e uma lacuna. Uma leitura CSV padrão pode retornar o inteiro 2139, texto de data, rótulos de categoria simples sem sua ordem e números de ponto flutuante para as contagens.

Uma leitura concluída sem erro, portanto, não necessariamente restaurou o DataFrame original. Guarde as opções necessárias para reconstruir os dados, incluindo identificadores de texto, interpretação de datas e marcadores de valores ausentes. A ordem das categorias também precisa ser definida novamente. Para análises repetidas em que esses tipos são importantes, Parquet pode preservá-los diretamente.

Acrescente registros e proteja a entrada bruta

df.to_csv(
    "daily_results.csv",
    mode="a",
    header=False,
    index=False
)

Isso adiciona linhas a um arquivo existente. Mantenha a ordem das colunas e as convenções consistentes com esse arquivo. Com header=True, um acréscimo grava outro cabeçalho no meio, e o próximo leitor pode tratá-lo como um registro. Para um arquivo novo, grave o cabeçalho uma vez antes dos acréscimos posteriores.

Mantenha arquivos recebidos ou baixados inalterados em um local de dados brutos. Grave resultados derivados separadamente com nomes descritivos. Ao abrir novamente uma exportação processada, confira a contagem de linhas, as colunas, os valores ausentes e valores representativos, incluindo zeros à esquerda e datas.

O melhor formato de armazenamento depende de quem lerá os dados em seguida e do que deve ser preservado na troca. Uma tabela enviada a um colega, uma resposta aninhada de API e um conjunto de dados tipado para análise têm necessidades diferentes.

Compare armazenamento de texto e binário

Formatos de texto codificam caracteres visíveis. CSV é fácil de inspecionar e amplamente aceito; JSON representa naturalmente objetos e arrays aninhados. CSV não tem um esquema de tipos de colunas, e os tipos comuns de valores JSON não preservam todos os tipos de dados do pandas. Relê-los exige interpretação e pode exigir escolhas explícitas de tipos.

Formatos binários codificam dados para leitura direta por programas. Formatos como Parquet e Feather armazenam um esquema que descreve colunas e tipos, reduzindo a necessidade de inferir tipos novamente. O suporte a tipos ainda depende do formato e do leitor: objetos Python arbitrários não se tornam portáveis apenas porque o arquivo é binário.

Uma estrutura orientada por linhas mantém juntos os campos de um registro. Uma estrutura colunar mantém juntos os valores da mesma coluna. Análises frequentemente precisam de poucas colunas de muitas linhas, por isso leitores colunares podem ignorar colunas desnecessárias. Valores adjacentes semelhantes também são bem comprimidos. O tamanho e a velocidade dependem dos dados; um resultado de compressão para uma tabela não é uma proporção fixa para todas as tabelas.

Associe cada formato a uma tarefa

Parquet é um formato aberto usado por pandas, R, Spark e DuckDB. Feather usa Arrow IPC e é útil para troca rápida entre Python e R ou entre etapas locais. to_feather e read_feather permitem essa troca. HDF5 agrupa vários conjuntos de dados em um arquivo; to_hdf do pandas exige PyTables.

Entenda o limite de confiança do pickle

pickle pode salvar objetos Python além de tabelas comuns, mas carregá-lo pode executar código. Nunca carregue um pickle de uma fonte não confiável. Use-o para seus próprios objetos de curta duração e espere limites de compatibilidade à medida que Python e as bibliotecas mudam. Por exemplo, o pandas 3 não oferece mais suporte à leitura de pickles criados com versões do pandas anteriores à 1.0.

Decida com base no resultado necessário

Se um destinatário precisar inspecionar uma tabela pequena sem ferramentas especiais, CSV é prático. Se precisar de planilhas nomeadas em uma pasta de trabalho, use Excel. Se você precisar preservar identificadores, categorias e tipos com suporte a valores ausentes entre sessões de análise, escolha Parquet. Se vários programas precisarem consultar e atualizar registros compartilhados, um banco de dados é mais adequado à tarefa que passar cópias de um arquivo. A escolha do formato depende do próximo uso, não da extensão da entrada original.

Parquet armazena uma tabela com os tipos das colunas em um formato aberto e colunar. É útil quando um DataFrame verificado será carregado repetidamente ou passado a outras ferramentas de análise. O pandas usa PyArrow nos exemplos abaixo.

Grave e verifique um ciclo de gravação e leitura com tipos preservados

df.to_parquet("sales.parquet", engine="pyarrow")
restored = pd.read_parquet("sales.parquet", engine="pyarrow")
print(restored.dtypes)

Um identificador de texto "02139", uma coluna de data e hora, uma categoria ordenada e inteiros com suporte a valores ausentes podem preservar seus tipos nesse ciclo do pandas para o PyArrow e de volta ao pandas. Diferentemente de uma leitura de CSV, não é necessário inferir a função do identificador nem recriar a ordem das categorias. Inspecione os tipos e valores representativos ao introduzir um novo leitor ou programa de gravação.

O padrão index=None armazena um RangeIndex de forma compacta como metadado. Outro índice é gravado como colunas e restaurado na leitura. Use index=False quando o índice não for necessário. Essa escolha diz respeito aos rótulos das linhas, independentemente das colunas comuns da tabela.

Leia menos dados e escolha a compressão

small = pd.read_parquet(
    "sales.parquet",
    columns=["zip", "amount"]
)

O leitor pode recuperar do armazenamento apenas essas colunas. Isso é diferente de carregar a tabela inteira e selecionar depois, pois nesse caso o custo da leitura completa já foi pago. A seleção de colunas é especialmente útil para tabelas com muitas colunas.

Snappy é o codec de compressão padrão. compression="zstd" ou "gzip" frequentemente exige mais trabalho de gravação em troca de menor espaço de armazenamento, enquanto compression=None grava dados sem compressão. Meça essa relação com dados representativos; rótulos repetidos e medidas aleatórias não são comprimidos da mesma forma. Instale PyArrow; o mecanismo alternativo fastparquet está obsoleto no pandas 3.1.

Organize um conjunto de dados em partições

df.to_parquet(
    "sales_dataset",
    engine="pyarrow",
    partition_cols=["year"],
    index=False
)
recent = pd.read_parquet(
    "sales_dataset",
    filters=[("year", "==", 2026)]
)

O destino é um diretório com subdiretórios como year=2025 e year=2026. Ler o diretório carrega o conjunto de dados; um filtro pode evitar partições não relacionadas. Nessa estrutura, o PyArrow obtém os valores de year dos nomes dos diretórios, e o pandas geralmente recebe uma coluna categórica de partição.

Escolha uma coluna de partição com um pequeno conjunto de valores úteis usados frequentemente em filtros. Um ID exclusivo de registro cria milhares de partições minúsculas, aumentando o trabalho com arquivos e diretórios. Ano ou um pequeno conjunto de regiões costuma oferecer uma divisão mais prática.

Adicione dados sem corromper o conjunto

Um único arquivo Parquet não permite acrescentar linhas pelo pandas como em CSV. Grave novos arquivos ou partições no diretório do conjunto de dados ou leia, combine e regrave um único arquivo. Arquivos que compõem um conjunto de dados precisam de esquemas compatíveis. Se um armazenar um código como texto e outro como inteiro, o carregamento poderá falhar ou converter valores. Defina tipos de dados consistentes antes de gravar cada parte e confira se uma partição adicionada não cria cópias sobrepostas dos mesmos registros.

Um banco de dados relacional armazena registros em tabelas com colunas nomeadas. Um programa envia uma consulta SQL por uma conexão e recebe um resultado que o pandas pode transformar em DataFrame. O banco de dados pode selecionar apenas os dados necessários antes de enviá-los ao Python.

Comece com um arquivo SQLite

import sqlite3
import pandas as pd

con = sqlite3.connect("shop.db")
try:
    df = pd.read_sql_query(
        "SELECT region, amount FROM sales", con
    )
finally:
    con.close()

SQLite funciona sem um servidor separado e armazena um banco de dados em um arquivo. A conexão cria o arquivo se ele não existir, por isso um caminho digitado incorretamente pode abrir um banco novo e vazio em vez do desejado. ":memory:" cria um banco de dados temporário na memória. A consulta acima retorna as colunas region e amount de uma tabela sales existente; os nomes das colunas do resultado tornam-se rótulos do DataFrame.

O bloco with de uma conexão SQLite gerencia uma transação, não o fechamento da conexão. Chame close() explicitamente ao terminar. Um bloco try/finally fecha a conexão mesmo se a leitura gerar um erro.

Use um mecanismo para um banco de dados de servidor

O SQLAlchemy fornece mecanismos para sistemas como PostgreSQL, MySQL e SQL Server, com um driver correspondente instalado. Uma URL de conexão identifica o dialeto, o driver, o servidor e o banco de dados. Mantenha-a em uma variável de ambiente:

import os
from sqlalchemy import create_engine

engine = create_engine(os.environ["ANALYSIS_DB_URL"])
try:
    with engine.connect() as conn:
        df = pd.read_sql_query(
            "SELECT region, amount FROM sales", conn
        )
finally:
    engine.dispose()

O contexto da conexão devolve a conexão ao conjunto de conexões do mecanismo. dispose() libera os recursos desse conjunto quando o mecanismo não é mais necessário. Use uma conta somente de leitura para análise e mantenha credenciais fora de cadernos computacionais e do controle de versão. Uma URL de mecanismo para um arquivo SQLite local pode ser "sqlite:///shop.db".

Escolha o leitor compatível com a entrada

Com uma conexão sqlite3 direta, passe uma consulta completa. pd.read_sql("sales", con) envia sales como SQL e falha; use pd.read_sql_query("SELECT * FROM sales", con). O pandas oferece suporte a conexões SQLAlchemy, ADBC e SQLite; uma conexão direta de driver arbitrário não é uma alternativa compatível apenas porque o driver consegue executar SQL.

Transfira o resultado necessário

Uma consulta que retorna linhas e colunas selecionadas transfere menos dados que ler uma tabela inteira e descartar a maior parte no pandas. A consulta fornecida SELECT SUM(amount) AS total FROM sales retorna um valor agregado, com o rótulo total. Ler o resultado de uma consulta não altera a tabela armazenada. Após o carregamento, confira a contagem de linhas e os tipos como faria com um arquivo; os tipos declarados no banco de dados e os tipos retornados pelo pandas estão relacionados, mas não são idênticos.

Valores variáveis devem ficar em parâmetros de consulta. A instrução SQL define a operação; os parâmetros vinculados fornecem a região, o limite ou outro valor usado nessa execução. Isso preserva a estrutura da consulta mesmo quando um valor contém uma aspa.

Vincule valores com a sintaxe da conexão

Para SQLite:

query = "SELECT region, amount, sold_on FROM sales WHERE amount > ? ORDER BY amount DESC"
df = pd.read_sql_query(query, con, params=(70,))

Para os valores de vendas 120,0, 75,5, 60,0 e 210,0, isso retorna 210,0, 120,0 e 75,5 em ordem decrescente. A tupla (70,) tem um elemento; (70) é apenas o número 70. SQLite também aceita marcadores de parâmetro nomeados, por exemplo, WHERE region = :r com params={"r": "North"}.

As regras dos marcadores dependem da interface. psycopg usa %s ou %(name)s. Com SQLAlchemy, envolva uma instrução em text e use parâmetros nomeados:

from sqlalchemy import text

query = text("SELECT region, amount FROM sales WHERE amount >= :m")
with engine.connect() as conn:
    df = pd.read_sql_query(query, conn, params={"m": 100})

Passe valores por params; não use formatação Python para inseri-los na instrução.

Entenda o que a parametrização protege

Suponha que um código construa uma condição usando uma f-string e uma entrada "x' OR '1'='1". Colá-la entre aspas altera a condição para region = 'x' OR '1'='1', que corresponde a todas as linhas. Isso é injeção de SQL: um valor tornou-se parte executável da estrutura da consulta.

Um parâmetro vinculado é comparado como um único valor, por isso essa mesma string corresponde apenas a uma região que tenha literalmente esse texto. A vinculação também trata nomes comuns que contêm apóstrofos sem necessidade de escapar aspas manualmente. A regra se aplica tanto a entradas de arquivos quanto de formulários de usuários.

Parâmetros representam valores, não nomes de tabelas ou colunas. Um parâmetro no lugar de um nome de tabela não seleciona essa tabela. Quando um programa precisar de um identificador variável, escolha-o em uma lista fixa controlada pelo código.

Controle os tipos no resultado

SQLite geralmente armazena datas como texto. Peça ao pandas que as interprete:

df = pd.read_sql_query(
    "SELECT sold_on, visits FROM observations", con,
    parse_dates=["sold_on"],
    dtype={"visits": "Int64"}
)

A coluna de data torna-se uma coluna de valores de data e hora, e uma contagem com NULL do SQL usa inteiros com suporte a valores ausentes em vez de se tornar ponto flutuante apenas para conter lacunas. Inspecione o resultado para conferir a conversão.

Diferencie blocos do armazenamento temporário pelo driver

chunksize=1000 retorna um iterador de DataFrames com no máximo 1.000 linhas cada. Um resultado de quatro linhas com chunksize=3 produz partes de três e uma linha. Mantenha a conexão aberta enquanto as processa. Alguns drivers de banco de dados ainda armazenam temporariamente o resultado inteiro antes de o pandas fornecer os blocos; um cursor no servidor ou uma configuração de leitura em fluxo também pode ser necessário para limitar a memória em todo o caminho da conexão.

to_sql cria uma tabela de banco de dados a partir de um DataFrame ou grava linhas em uma tabela existente. Suas opções determinam se os dados existentes são preservados, se o índice se torna uma coluna e como um grupo de gravações é confirmado.

Escolha o comportamento para uma tabela existente

df.to_sql("sales", con, index=False)

O padrão if_exists="fail" interrompe a operação quando sales já existe. Escolha outro modo apenas quando seu efeito corresponder à carga desejada:

delete_rows está disponível no pandas 3. Substituir uma tabela remove sua definição antiga, incluindo chaves, índices e restrições; permissões específicas do banco de dados também podem ser afetadas. Excluir linhas preserva a definição, mas ainda apaga todos os registros existentes. Use essa opção para uma recarga completa pretendida, não quando o DataFrame contiver apenas um novo lote.

Defina as colunas e grave em uma transação

O padrão grava o índice do DataFrame como coluna. Um índice sem nome torna-se index; um índice nomeado mantém o nome. index_label fornece um nome explícito, e index=False o exclui. Se um ID já for uma coluna comum, gravar os números de linha padrão geralmente não acrescenta informação útil.

Com SQLAlchemy, dtype pode escolher tipos do banco de dados:

from sqlalchemy import types

with engine.begin() as conn:
    df.to_sql(
        "sales", conn,
        if_exists="append",
        index=False,
        dtype={"sold_on": types.Date()},
        chunksize=1000
    )

engine.begin() confirma a transação quando o bloco termina sem erro e a reverte em caso de exceção. Para uma tabela existente, o esquema armazenado ainda determina quais valores podem ser inseridos; dtype não é um comando para redesenhar as colunas. As garantias da transação também dependem do suporte do banco de dados às operações usadas. Acrescentar dados dentro de uma transação SQLAlchemy mantém unida a carga de inserção do exemplo.

chunksize agrupa linhas em lotes. method="multi" coloca várias linhas em uma instrução INSERT onde houver suporte. Isso pode melhorar ou reduzir o desempenho dependendo do banco de dados e do tamanho do lote, por isso meça com dados representativos.

Verifique o crescimento, não apenas a conclusão

check = pd.read_sql_query("SELECT COUNT(*) AS n FROM sales", con)
print(check["n"].iloc[0])

Para uma tabela nova ou totalmente recarregada, compare a contagem com len(df). Para um acréscimo, compare o aumento: uma tabela com quatro linhas que recebe duas deve conter seis. A contagem de linhas retornada por to_sql vem do que o driver informa; verifique os dados armazenados diretamente.

Executar um acréscimo duas vezes repete os registros, a menos que o banco de dados rejeite duplicatas ou o programa selecione apenas registros novos. Decida se a operação é uma recarga completa ou um acréscimo de novos registros antes de executá-la novamente. Uma transação impede uma carga parcial em caso de falha; ela não torna únicos acréscimos bem-sucedidos repetidos.