Como usar LookupRows no AMPscript (e quando trocar por Lookup ou LookupOrderedRows)

Quando um assinante pode ter várias linhas relacionadas numa Data Extension (pedidos, cursos, agendamentos), você precisa buscar todas elas e montar uma lista dentro do e-mail. É para isso que existe o LookupRows.

As três funções de busca

Nas três, o primeiro parâmetro é o nome da Data Extension, não a chave externa.

Sintaxe do LookupRows

LookupRows("NomeDaDE", "Coluna1", "Valor1" [, "Coluna2", "Valor2", ...])

Cada par coluna/valor é um filtro de igualdade, e os pares se combinam com "E".

Exemplo: pedidos do assinante

A Data Extension Pedidos tem as colunas Email, Numero, Valor e Status.

%%[
SET @email   = AttributeValue("EmailAddress")
SET @pedidos = LookupRows("Pedidos", "Email", @email, "Status", "Enviado")
SET @total   = RowCount(@pedidos)

IF @total > 0 THEN
]%%
<p>Você tem %%=v(@total)=%% pedido(s) a caminho:</p>
<ul>
%%[
  FOR @i = 1 TO @total DO
    SET @linha  = Row(@pedidos, @i)
    SET @numero = Field(@linha, "Numero")
    SET @valor  = Field(@linha, "Valor")
]%%
  <li>Pedido %%=v(@numero)=%%: R$ %%=FormatNumber(@valor, "N2", "pt-BR")=%%</li>
%%[
  NEXT @i
]%%
</ul>
%%[ ELSE ]%%
<p>Nenhum pedido a caminho no momento.</p>
%%[ ENDIF ]%%

As peças:

• RowCount(@rowset) diz quantas linhas vieram;
• Row(@rowset, @i) pega a linha de número @i (a contagem começa em 1);
• Field(@linha, "Coluna") lê uma coluna daquela linha.

Ordenar e limitar com LookupOrderedRows

Para mostrar só os 3 pedidos mais recentes, troque por LookupOrderedRows, que recebe a quantidade e a ordenação antes dos filtros:

%%[
SET @ultimos = LookupOrderedRows("Pedidos", 3, "DataPedido DESC", "Email", @email)
SET @total   = RowCount(@ultimos)
]%%

A ordenação aceita mais de uma coluna, separadas por vírgula: "DataPedido DESC, Numero ASC".

Desempenho e limites

• LookupRows devolve no máximo 2.000 linhas. Se precisar de mais, o e-mail não é o lugar certo para essa lista.
• Cada função de busca é executada para cada assinante do envio. Em envios grandes, evite repetir a mesma busca: guarde o resultado numa variável e reutilize.
• Filtrar por colunas que fazem parte da chave primária da Data Extension costuma ser mais rápido.

Resumo

Use Lookup para um valor, LookupRows para várias linhas e LookupOrderedRows quando a ordem ou o limite importam. Teste RowCount antes de percorrer o resultado e lembre do limite de 2.000 linhas.