Índices de pesquisa

Essas rotas reconstroem índices de pesquisa a partir de dados atuais e relatam o progresso. As reconstruções aparecem em Jobs como refreshSearchIndex.

Ambas as rotas requerem a ACL guild:lookup.

Nomes de índices de pesquisa

index_name é um dos seguintes valores. Um valor fora do conjunto falha na validação do caminho.

Valor	Escopo	Descrição
guilds	Toda a instância	Todos os servidores (guilds), respaldando a pesquisa administrativa de servidores
users	Toda a instância	Todas as contas, respaldando a pesquisa administrativa de usuários
reports	Toda a instância	Todos os relatórios, respaldando a pesquisa administrativa de relatórios
audit_logs	Toda a instância	Todas as entradas de auditoria do Admin, respaldando a pesquisa administrativa de auditorias
discovery¹	Toda a instância	Metadados de descoberta escritos nos documentos de servidor de listagens aprovadas
channel_messages²	Um servidor	Mensagens de todos os canais em um servidor, requerendo `guild_id`
guild_members³	Um servidor	Membros de um servidor, requerendo `guild_id`
favorite_memes⁴	Um usuário	Memes favoritados de um usuário, requerendo `user_id`

¹ Atualiza a descrição, categoria, idioma principal e tags de listagens de descoberta aprovadas sem remover servidores da pesquisa

² Limpa o índice de mensagens do servidor e enfileira jobs indexChannelMessages para seus canais. A conclusão do job pai não significa que esses jobs terminaram

³ Limpa primeiro o índice de membros do servidor e atualiza members_indexed_at após a conclusão

⁴ A reconstrução deste índice não é suportada. A solicitação é aceita, mas o job falha sem relatar o progresso

Todo nome que abrange toda a instância, exceto discovery, exclui seus documentos antes que o primeiro lote seja gravado, portanto a pesquisa nesse índice fica incompleta durante toda a execução.

Uma reconstrução discovery, em vez disso, atualiza os documentos de servidor existentes no local, de forma que esses documentos permanecem pesquisáveis durante toda a execução.

Objeto de atualização do índice de pesquisa

Um recibo para uma reconstrução enfileirada.

Estrutura

Campo	Tipo	Descrição
success	boolean	Sempre verdadeiro (true)
job_id¹	string	O ID da reconstrução enfileirada, usado para ler seu progresso

¹ O valor é um snowflake renderizado como uma string. Ele endereça o registro de progresso que Obter atualização do índice de pesquisa lê. Difere do job_id da entrada no registro de Jobs para a mesma reconstrução, e aparece lá apenas dentro do payload daquela entrada

Exemplo

{
  "success": true,
  "job_id": "1501314428688998182"
}

Objeto de progresso da atualização do índice de pesquisa

Progresso para uma reconstrução enfileirada. A forma do objeto é selecionada por status.

Estrutura não encontrada

Campo	Tipo	Descrição
status	string	Sempre `not_found`

Estrutura de progresso

Campo	Tipo	Descrição
status	string	Um entre `in_progress`, `completed` ou `failed`
index_type	string	O nome do índice de pesquisa sendo reconstruído
total?¹	number	O número de documentos esperados, presente enquanto a reconstrução relata progresso e quando ela é concluída
indexed?²	number	O número de documentos gravados até agora
started_at?³	ISO8601 timestamp	A hora em que a reconstrução relatou progresso pela última vez
completed_at?	ISO8601 timestamp	A hora em que a reconstrução terminou, presente apenas quando `status` é `completed`
failed_at?	ISO8601 timestamp	A hora em que a reconstrução falhou, presente apenas quando `status` é `failed`
error?	string	O texto da falha, presente apenas quando `status` é `failed`

¹ total é o mesmo valor que indexed enquanto a reconstrução é executada e se torna o total real na conclusão. A reconstrução discovery relata a contagem de listagens aprovadas a partir de seu primeiro lote

² Cada documento que a reconstrução grava conta como um. Uma reconstrução channel_messages conta os canais que ela enfileirou

³ Reescrito em cada relatório de progresso, então seu valor avança enquanto a reconstrução é executada

Um resultado com falha inclui status, index_type, error e failed_at, mas nem total nem indexed.

Exemplo

{
  "status": "in_progress",
  "index_type": "guilds",
  "total": 3000,
  "indexed": 3000,
  "started_at": "2026-08-31T09:12:44.118Z"
}

Atualizar índice de pesquisa

POST/v1/admin/search/indexes/{index_name}/refreshes

Audit reason

Enfileira uma reconstrução do índice nomeado. Requer guild:lookup. Retorna um objeto de atualização do índice de pesquisa em caso de sucesso.

Parâmetros de caminho

Campo	Tipo	Descrição
index_name	string	O nome do índice de pesquisa para reconstruir

Corpo JSON

Todo campo é opcional. O Decoding Chat lê um corpo ausente ou vazio como um objeto vazio, então uma reconstrução de toda a instância pode enviar nenhum corpo. Um corpo que não seja um JSON parseável retorna 400 INVALID_FORM_BODY com o código de validação INVALID_FORMAT no caminho body.

Campo	Tipo	Descrição
guild_id?¹	snowflake	O ID do servidor (guild) cujos documentos no índice são reconstruídos
user_id?²	snowflake	O ID do usuário cujos documentos no índice são reconstruídos

¹ Obrigatório para channel_messages e guild_members. Qualquer outro nome de índice o ignora

² Obrigatório para favorite_memes. Qualquer outro nome de índice o ignora

O Decoding Chat registra ambos os valores na entrada de auditoria sempre que são fornecidos, incluindo em um nome de índice que os ignora.

Resposta

Status	Corpo	Condição
200	objeto de atualização do índice de pesquisa	A reconstrução foi enfileirada
400	resposta de erro	`INVALID_FORM_BODY` porque o ID de escopo que o nome do índice requer está ausente, ou o corpo não é um JSON parseável
403	resposta de erro	`MISSING_PERMISSIONS` sem `admin:authenticate`, ou `MISSING_ACL` sem `guild:lookup`
500	resposta de erro	O job não pôde ser enfileirado

Um ID de escopo ausente nomeia guild_id ou user_id em errors. O Decoding Chat não enfileira nenhum job e não registra nenhuma entrada de auditoria para essa falha.

Efeitos colaterais

Uma reconstrução no escopo de servidor para um servidor desconhecido produz um índice vazio.

Uma reconstrução que falhou não é tentada novamente de forma automática.

O Decoding Chat registra uma entrada de auditoria de Admin com a ação queue_refresh_index, o tipo de destino search_index e o ID de destino 0. Seus metadados contêm index_type, job_id e o que foi fornecido entre guild_id e user_id na solicitação. O Decoding Chat não emite nenhum Gateway Dispatch.

Limite de taxa

200 solicitações por minuto para cada usuário autenticado, no bucket admin:lookup.

Obter atualização de índice de pesquisa

GET/v1/admin/search/index-refreshes/{job_id}

Retorna o objeto de progresso da atualização do índice de pesquisa para uma reconstrução enfileirada. Requer guild:lookup.

Parâmetros de caminho

Campo	Tipo	Descrição
job_id¹	string	O identificador retornado por Atualizar índice de pesquisa

¹ O valor é limitado de 1 a 128 caracteres depois que o Decoding Chat remove cada caractere form feed (U+000C) e substituição da direita para a esquerda (right-to-left override) (U+202E) e apara (trims) os espaços em branco de ambas as extremidades. Não precisa ser um snowflake

Resposta

Status	Corpo	Condição
200¹	objeto de progresso da atualização do índice de pesquisa	Um registro de progresso foi retornado, incluindo a forma de não encontrado
403	resposta de erro	`MISSING_PERMISSIONS` sem `admin:authenticate`, ou `MISSING_ACL` sem `guild:lookup`

¹ Um identificador desconhecido responde 200 com status definido como not_found, que também é a resposta para um registro expirado e para uma reconstrução que falhou antes de gravar seu primeiro registro

Efeitos colaterais

A operação não registra nenhuma entrada de auditoria de Admin.

Limite de taxa

200 solicitações por minuto para cada usuário autenticado, no bucket admin:lookup.