We ran a query to count the failed orders from last week.
Rodamos uma query para contar os pedidos com falha da semana passada.Aula
Banco de dados e queries B1
Nível: B1
Objetivo
Explicar problemas de dados e alterações de schema em inglês usando query, transaction, constraint, migration, index e join, descrevendo causas, impactos e próximos passos para o time.
Explicação
Em discussões técnicas sobre banco de dados, alguns termos funcionam como peças fixas. Query é qualquer comando enviado ao banco para ler ou alterar dados: `We ran a query to count the failed orders.` Transaction é um bloco de operações que precisa terminar junto — ou tudo grava, ou nada grava: `The transaction updated two tables and committed.`
Schema é a estrutura das tabelas (colunas, tipos, relações); migration é a mudança versionada dessa estrutura: `We shipped a migration that adds a new column to the users table.` Para falar de regras de validação embutidas no schema, use constraint: `The constraint requires the email to be unique.`
Index é uma estrutura auxiliar que acelera buscas em colunas específicas: `Adding an index on the created_at column made the query much faster.` Lembre que índices têm custo: deixam `INSERT` e `UPDATE` um pouco mais lentos, então não se indexa tudo.
Join é a operação que combina linhas de duas ou mais tabelas por uma coluna em comum. Os tipos mais comuns no dia a dia são `INNER JOIN` (só linhas com correspondência nas duas tabelas), `LEFT JOIN` (todas as linhas da tabela da esquerda, com `NULL` quando não há correspondência) e `RIGHT JOIN` (o oposto). Para falar do problema, diga: `The report was missing customers because we used an inner join instead of a left join.`
Para explicar um problema de dados, siga um mini-roteiro: o que estava errado (`The query returned duplicate rows`), a causa provável (`The join condition was missing the status filter`), o impacto (`The dashboard overcounted active users`), e o que fazer em seguida (`We will add a constraint and a backfill migration`). Esse padrão `symptom → cause → impact → next step` é o mesmo em incident reviews, post-mortems e tickets.
Para explicar uma alteração de schema, comece dizendo o que muda, em qual tabela, e se a mudança é compatível com a versão anterior. Mudanças aditivas (nova coluna, nova tabela) são compatíveis; mudanças destrutivas (renomear coluna, mudar tipo, remover coluna) exigem cuidado e geralmente vêm em duas ou três migrations. Frases úteis: `This migration is backward compatible.`, `The old column will be removed in a follow-up migration.`, `The change is gated behind a feature flag.`
Quando precisar investigar, peça dados de forma específica: `Can you share the exact query that failed?`, `What was the error message?`, `Was the transaction committed or rolled back?` Respostas como `It threw a constraint violation` ou `The index wasn't used because the column had a function on it` mostram que você entende o problema e ajuda o time a ir direto para a correção.
Exemplos
| Inglês | Tradução | Observação |
|---|---|---|
| We ran a query to count the failed orders from last week. | Rodamos uma query para contar os pedidos com falha da semana passada. | Query pode ser usada como substantivo ou verbo (to run a query). |
| The transaction updated two tables and then committed. | A transação atualizou duas tabelas e depois fez commit. | Transaction é o bloco; commit registra as mudanças. |
| The constraint requires the email column to be unique. | A constraint exige que a coluna de e-mail seja única. | Constraint = regra de validação no schema. |
| We shipped a migration that adds a new column to the users table. | Subimos uma migration que adiciona uma coluna nova na tabela de usuários. | Migration = mudança versionada do schema. |
| Adding an index on the created_at column made the dashboard query much faster. | Adicionar um índice na coluna created_at deixou a query do dashboard bem mais rápida. | Index acelera leituras, mas tem custo em escritas. |
| The report was missing customers because we used an inner join instead of a left join. | O relatório estava perdendo clientes porque usamos um inner join em vez de um left join. | Join combina tabelas; o tipo muda o resultado. |
| The exact query that failed is in the ticket, and the error was a constraint violation on the email column. | A query exata que falhou está no ticket, e o erro foi uma violação de constraint na coluna de e-mail. | Padrão útil para resumir um bug de banco em poucas frases. |
Erros comuns
- Confundir 'a query' com 'the query' na primeira menção; em inglês técnico use `a query` ao introduzir e `the query` ao retomar.
- Dizer 'made a transaction' quando o termo é `ran a transaction` ou `started a transaction`; 'make' não combina com transaction em contexto de banco.
- Trocar 'commit' e 'rollback': `commit` confirma as mudanças, `rollback` desfaz; dizer `we committed but then we rolled back` descreve uma transação que terminou sem efeito.
- Usar 'indexes' no singular com artigo errado; o plural comum é `indexes`, e a forma latinada `indices` é mais rara em código e SQL.
- Misturar 'inner join' e 'left join' ao descrever o bug; o sintoma quase sempre vem do tipo errado de join, então nomeie-o ao explicar.
- Dizer 'we changed the schema' sem dizer se a mudança é compatível; sempre mencione `backward compatible` ou `breaking change` ao falar de migrations.
Prática guiada
Reescreva cada nota em uma explicação curta de banco, seguindo o padrão `symptom → cause → impact → next step`:
- Nota solta: `a query duplicou as linhas.`
Em explicação: `The query returned duplicate rows because the join condition was missing the status filter, so the dashboard overcounted active users. We will add a constraint and ship a backfill migration.`
- Nota solta: `a migration removeu a coluna antiga.`
Em explicação: `That migration removed the old column, which is a breaking change for older clients. We will ship it behind a feature flag and remove the column in a follow-up migration.`
- Nota solta: `o INSERT ficou lento depois do deploy.`
Em explicação: `Inserts got slower after we added the index, which is the expected trade-off. We will keep the index because the read query is on the hot path.`
Note que cada explicação nomeia o problema, a causa provável, o impacto e a próxima ação.
Resumo
Query lê ou altera dados, transaction agrupa operações que precisam ir juntas, constraint é uma regra de validação no schema, migration é a mudança versionada dessa estrutura, index acelera leituras com custo em escritas, e join combina linhas de duas ou mais tabelas. Para explicar um problema, siga `symptom → cause → impact → next step`; para explicar uma alteração de schema, diga o que muda e se a migration é backward compatible ou breaking change.
Vocabulário
Palavras principais
Can you run a query against the staging database?
Você pode rodar uma query no banco de staging?The transaction updated two tables and then committed.
A transação atualizou duas tabelas e depois fez commit.If the second insert fails, the transaction is rolled back.
Se o segundo insert falhar, a transação sofre rollback.The constraint requires the email column to be unique.
A constraint exige que a coluna de e-mail seja única.The insert failed with a constraint violation on the email column.
O insert falhou com uma violação de constraint na coluna de e-mail.The schema defines every column and its data type.
O schema define cada coluna e o tipo de dado dela.We shipped a migration that adds a new column to the users table.
Subimos uma migration que adiciona uma coluna nova na tabela de usuários.This migration is backward compatible with the previous release.
Esta migration é compatível com a versão anterior.Removing a column is a breaking change for older clients.
Remover uma coluna é uma breaking change para clientes antigos.Adding an index on the created_at column made the query much faster.
Adicionar um índice na coluna created_at deixou a query bem mais rápida.The report was missing customers because we used an inner join instead of a left join.
O relatório estava perdendo clientes porque usamos um inner join em vez de um left join.An inner join drops rows that don't match on both sides.
Um inner join descarta linhas que não casam nos dois lados.Use a left join when you want to keep every row from the first table.
Use um left join quando você quer manter toda linha da primeira tabela.Each row represents one customer in the table.
Cada linha representa um cliente na tabela.The users table has a column for email and another for created_at.
A tabela de usuários tem uma coluna para e-mail e outra para created_at.We store the orders in a separate table.
Guardamos os pedidos em uma tabela separada.The migration protects data integrity by adding a unique constraint.
A migration protege a integridade dos dados adicionando uma constraint única.História
História: Banco de dados e queries B1
Nível: B1
História em inglês
The dashboard that didn't match
On Wednesday morning, the growth team opened a ticket: the active-users dashboard showed almost twice as many users as expected. Sofia, the data engineer, took the ticket and asked, "Can you share the exact query that the dashboard is running?" The analyst sent the query, and Sofia noticed that it was joining the users table with the events table. She said, "The query is using an inner join, so any user without events is dropped, and any user with more than one event is counted multiple times." "That explains the count," the analyst replied, "but the report has been wrong for weeks. Why didn't anyone catch it earlier?"
From symptom to fix
Sofia explained the issue in three steps: symptom, cause, and next step. First, the symptom: the query returned duplicate rows, so the dashboard overcounted active users. Second, the cause: the join condition was missing a status filter, which let canceled users slip into the count. "We also need to protect data integrity," she added, "so the next step is to ship a migration that adds a not-null constraint on the status column." The analyst asked, "Will the migration be backward compatible with the current release?" "Yes," Sofia answered, "it's just a new constraint and a backfill for old rows, so older clients won't break."
A follow-up migration
Two days later, Sofia opened a second pull request to improve performance. She explained, "The dashboard query is still slow, so we are adding an index on the created_at column of the events table." "Will the index slow down inserts?" the product manager asked. "Slightly, but the dashboard query is on the hot path, so the trade-off is worth it," Sofia replied. She also said, "Once the index is in place, we will backfill the new status column and run a final query to confirm the count matches the source of truth." By the end of the week, the dashboard was back to the correct number, and the team had a clearer plan for future schema changes.
Tradução linha por linha
| Inglês | Tradução |
|---|---|
| On Wednesday morning, the growth team opened a ticket: the active-users dashboard showed almost twice as many users as expected. | Na manhã de quarta-feira, o time de growth abriu um ticket: o dashboard de usuários ativos mostrava quase o dobro de usuários do que o esperado. |
| Sofia, the data engineer, took the ticket and asked, "Can you share the exact query that the dashboard is running?" | Sofia, a engenheira de dados, pegou o ticket e perguntou: "Você consegue compartilhar a query exata que o dashboard está rodando?" |
| The analyst sent the query, and Sofia noticed that it was joining the users table with the events table. | O analista enviou a query, e Sofia percebeu que ela estava fazendo join da tabela de usuários com a tabela de eventos. |
| She said, "The query is using an inner join, so any user without events is dropped, and any user with more than one event is counted multiple times." | Ela disse: "A query está usando um inner join, então qualquer usuário sem evento é descartado, e qualquer usuário com mais de um evento é contado várias vezes." |
| "That explains the count," the analyst replied, "but the report has been wrong for weeks. Why didn't anyone catch it earlier?" | "Isso explica a contagem", respondeu o analista, "mas o relatório está errado há semanas. Por que ninguém percebeu antes?" |
| Sofia explained the issue in three steps: symptom, cause, and next step. | Sofia explicou o problema em três etapas: sintoma, causa e próximo passo. |
| First, the symptom: the query returned duplicate rows, so the dashboard overcounted active users. | Primeiro, o sintoma: a query retornou linhas duplicadas, então o dashboard superestimou os usuários ativos. |
| Second, the cause: the join condition was missing a status filter, which let canceled users slip into the count. | Segundo, a causa: a condição de join estava sem um filtro de status, o que deixou usuários cancelados entrarem na contagem. |
| "We also need to protect data integrity," she added, "so the next step is to ship a migration that adds a not-null constraint on the status column." | "Também precisamos proteger a integridade dos dados", ela acrescentou, "então o próximo passo é subir uma migration que adiciona uma constraint not-null na coluna de status." |
| The analyst asked, "Will the migration be backward compatible with the current release?" | O analista perguntou: "A migration vai ser compatível com a versão atual?" |
| "Yes," Sofia answered, "it's just a new constraint and a backfill for old rows, so older clients won't break." | "Sim", respondeu Sofia, "é só uma constraint nova e um backfill para as linhas antigas, então os clientes mais antigos não vão quebrar." |
| Two days later, Sofia opened a second pull request to improve performance. | Dois dias depois, Sofia abriu um segundo pull request para melhorar a performance. |
| She explained, "The dashboard query is still slow, so we are adding an index on the created_at column of the events table." | Ela explicou: "A query do dashboard ainda está lenta, então estamos adicionando um índice na coluna created_at da tabela de eventos." |
| "Will the index slow down inserts?" the product manager asked. | "O índice vai deixar os inserts mais lentos?", perguntou a product manager. |
| "Slightly, but the dashboard query is on the hot path, so the trade-off is worth it," Sofia replied. | "Um pouco, mas a query do dashboard está no caminho quente, então a troca vale a pena", respondeu Sofia. |
| She also said, "Once the index is in place, we will backfill the new status column and run a final query to confirm the count matches the source of truth." | Ela também disse: "Quando o índice estiver no lugar, vamos preencher a coluna de status nova e rodar uma query final para confirmar que a contagem bate com a fonte da verdade." |
| By the end of the week, the dashboard was back to the correct number, and the team had a clearer plan for future schema changes. | No fim da semana, o dashboard voltou ao número correto, e o time tinha um plano mais claro para mudanças de schema no futuro. |
Notas de vocabulário
- query = substantivo comum em tickets e reviews; também aparece como verbo (to run a query)
- inner join = combina apenas linhas com correspondência nas duas tabelas; pode descartar dados sem correspondência
- join condition = condição que liga duas tabelas no join; um filtro faltando aqui é causa comum de bug
- data integrity = garantia de que os dados seguem as regras do schema, geralmente reforçada por constraints
- not-null constraint = constraint que impede valores nulos em uma coluna; protege a integridade dos dados
- migration = mudança versionada do schema; pode ser backward compatible ou breaking change
- backward compatible = compatível com versões anteriores; clientes antigos continuam funcionando
- backfill = preencher dados antigos em uma coluna nova; costuma acompanhar uma migration
- index = acelera leituras, mas tem custo em escritas; é um trade-off comum em banco
- hot path = código executado com muita frequência; otimizações nesse caminho valem o trade-off
Perguntas de compreensão
- What was the symptom of the bug in the dashboard?
- Why did the query return duplicate rows?
- What kind of join was the query using, and what would have been a safer choice?
- What is the next step Sofia proposed to protect data integrity?
- Why did Sofia say the migration was backward compatible?
- Why did the team add an index on the created_at column, and what was the trade-off?
Prática com a história
- Reescreva em uma frase curta: 'A query duplicou as linhas porque faltava um filtro de status no join.'
- Traduza: 'A migration é compatível com a versão anterior.'
- Reescreva em formato de causa e efeito: 'Adicionamos um índice na coluna created_at, então a query do dashboard ficou bem mais rápida.'
- Traduza: 'Vamos subir uma migration que adiciona uma constraint not-null na coluna de status.'
Prática
Exercícios e teste
A próxima melhoria é transformar esses arquivos em perguntas com resposta no navegador. Por enquanto, esta página já organiza o estudo e permite seguir a aula inteira sem abrir os arquivos manualmente.