Mantenha a pesquisa de palavras-chave do TikTok comparável entre grupos de consultas

Monte seu plano de coleta

A entrada pública salva da Task usa três consultas de amostra, `expandQueries` definido como false, um teto compartilhado de `maxResults` de 150 vídeos únicos, `resultsPerQuery` definido como 50, `maxPagesPerQuery` definido como 1 e `searchDistribution` definido como "balanced". Substitua essas consultas de amostra pelos seus termos-alvo antes de executar um painel completo.

Para verificar sua configuração na build pública do Search 1.1.5, comece com uma execução piloto limitada. Substitua a lista de consultas de amostra por um termo pretendido. Defina `expandQueries` como false, `maxExpandedQueries` como 0, `maxResults` como 2, `resultsPerQuery` como 2, `maxPagesPerQuery` como 1 e `searchDistribution` como "balanced".

Uma verificação de linha de base com "python tutorial" retornou duas linhas de metadados com IDs de post, URLs de post, IDs de autor, handles, datas de publicação de maio e de agosto e um motivo de parada de OUTPUT igual a `max_results_reached`. Este piloto confirma campos básicos de busca e proveniência, mas não é um benchmark de tendência com várias consultas nem um teste de campanha de anúncios.

Campos nativos do conjunto de dados e evidência da execução

Os registros nativos do conjunto de dados incluem `postId`, `postUrl`, `authorId`, `profileHandle`, `publishedAt` e `observedAt`. Os campos de proveniência da busca rastreiam o contexto da consulta: `rootQuery` é a família original, `query` é o termo de busca executado e `querySource` identifica a origem desse termo. Os campos `pageIndex` e `pageRank` registram a posição na página de origem coletada. Os campos `status` e `statusReason` informam os estados de resultado no nível do item. Os campos opcionais permanecem nulos se faltarem na origem.

O objeto `OUTPUT` fornece evidência da execução, e não um mapeamento automatizado de consultas. Os campos principais incluem:

• `queriesSearched`: Array de termos realmente executados.
• `queryPlans`: Lista planejada de definições de consulta, raiz e origem.
• `effectiveResultsPerQuery`: Limite reduzido de vídeos salvos por termo, calculado durante a distribuição equilibrada.
• `rowsSaved`: Total de vídeos únicos gravados no conjunto de dados.
• `duplicatesSkipped`: Vídeos candidatos omitidos pela desduplicação global.
• `stopReason`: Estado geral de parada da execução, como `max_results_reached`.
• `sourceStatusCounts`: Estados de origem agregados, como `{ok: 1}`.
• `status` e `statusReason`: Resultado de execução de nível superior, como `status: "ok"` e `statusReason: null`.

Na execução de controle com uma única consulta, `OUTPUT` informou `stopReason: "max_results_reached"`, `rowsSaved: 2`, `sourceStatusCounts: {ok: 1}`, `status: "ok"` e `statusReason: null`.

Uma fração útil é definida como vídeos com ID conhecido, revisados e relevantes, divididos pela amostra comparável de candidatos revisáveis daquele termo tentado; termos com falha ou não tentados não têm fração válida.

Monte seu plano de coleta

1. Defina sua pergunta de pesquisa e as famílias de consultas antes de buscar. Agrupe termos somente quando eles representarem o mesmo conceito e mantenha uma lista explícita de consultas.
2. Defina o `maxResults` compartilhado, `resultsPerQuery`, `maxPagesPerQuery`, a escolha de expansão e `searchDistribution`. Desative a expansão ao comparar uma lista fixa exata. Um `maxResults` compartilhado funciona como teto total de vídeos salvos em todas as consultas, enquanto `resultsPerQuery` limita termos individuais.
3. Escolha a distribuição equilibrada quando precisar de uma parcela planejada entre os termos. Escolha a distribuição sequencial somente quando o objetivo for preencher os termos anteriores primeiro. A distribuição equilibrada pode reduzir o `effectiveResultsPerQuery` para dividir o limite total, mas não garante que as cotas serão preenchidas nem que a alocação não usada será realocada.
4. Separe o orçamento planejado dos dados úteis reais. Registre o status de tentativa, as linhas salvas, os IDs de vídeo conhecidos, as duplicatas, a identidade ausente e os estados de falha da origem. Zero linhas úteis após uma falha da origem indica disponibilidade desconhecida, não interesse zero no tema.
5. Preserve a proveniência e trate a desduplicação global com cuidado. Proveniência significa manter a origem salva exata e o horário de coleta registrados em `observedAt`. A desduplicação global nativa salva um vídeo apenas uma vez, sob a primeira consulta observada. Para capturar cada aparição em uma consulta, mantenha registros de execução separados por consulta.
6. Aplique a mesma regra manual de relevância a todos os grupos. Distinga vídeos candidatos de itens úteis ao verificar os valores exatos de `postId` e `postUrl`. Calcule frações úteis usando somente dados tentados e utilizáveis, e trate termos com falha ou não tentados como desconhecidos.
7. Relate as lacunas antes de comparar grupos. Marque termos não tentados como `not_attempted`, e não como zero, e mantenha os limites de teto da origem visíveis. Nunca classifique grupos de consultas somente por contagens totais brutas quando os limites de coleta ou as falhas diferem.
8. Salve seu plano de consultas e o registro real da amostra. Revise campos de `OUTPUT` como `queriesSearched`, `queryPlans`, `rowsSaved`, `duplicatesSkipped` e `stopReason` para registrar a evidência exata de parada antes de realizar a análise de tendência ou a análise de criativos.

Registros originais fictícios de coleta

Todos os valores abaixo são ficção original criada para ilustrar orçamentos de coleta, estados de parada e limites da desduplicação global. Eles não representam benchmarks reais do produto nem resultados do piloto.

Considere três termos, A, B e C, com `maxPagesPerQuery` definido como 1, expansão desativada, `maxResults` definido como 6 e `resultsPerQuery` solicitado definido como 6.

• Execução equilibrada: o `effectiveResultsPerQuery` informado é 2, o que cria um limite planejado de 2 vídeos salvos por termo. Se cada termo retornar 2 vídeos relevantes distintos, o registro mostra A=2, B=2, C=2 e salva 6 vídeos no total. A fração útil é 2/2 para cada termo.
• Execução sequencial: o limite configurado por termo é 6 para os termos A, B e C. O termo A retorna 6 vídeos salvos e preenche o teto compartilhado de `maxResults` de 6. Os termos B e C nunca são tentados. O registro anota Máximo planejado 6 para cada termo, com A=6 salvos, B=0 salvos (`not_attempted`) e C=0 salvos (`not_attempted`). Registrar 0 linhas salvas para B e C é escrituração; a disponibilidade da amostra deles permanece desconhecida.
• Falha da origem na execução equilibrada: o termo A salva 2 vídeos úteis (fração 2/2), o termo C salva 2 vídeos úteis (fração 2/2) e o termo B encontra um erro da origem. O termo B registra 0 linhas salvas, 0 linhas úteis e uma fração de relevância desconhecida. O rótulo `source_failed` é uma notação do registro do leitor, não um enum nativo do conjunto de dados.

Registro fictício de pertencimento às consultas

Uma execução fictícia separada de consultas avalia aparições de vídeos entre termos sem que a desduplicação global filtre as sobreposições.

Esta tabela de pertencimento contém 6 pertencimentos no total, em 5 IDs de vídeo distintos. Uma única exportação com desduplicação global retém V2 somente sob o termo A. Reter a proveniência do termo A para V2 não prova que V2 estava ausente do termo B. O pertencimento completo às consultas só pode ser rastreado ao salvar registros de execução limitados e separados para cada consulta.