aggrega search
Pesquisar o índice local dos registos configurados
Sinopse
aggrega search [query] [flags]Descrição
Search the local index of the configured registries for entities matching afree-text query and optional facet filters.
The index is the offline snapshot written by 'aggrega registry update'; searchreads it and contacts no network. Run 'aggrega registry update' first, and againwhenever you want to pick up newly published entities. A freshness line namingeach searched registry and when its index was last updated is written to standarderror, so standard output carries only the result data.
The optional positional query is a case-insensitive substring matched againsteach entity's name and description. The facet filters narrow the result further,combining as AND across facets and OR within a repeatable facet:
--kind entity kind (component, feature, recipe, featurerecipe, workload, plugin); repeatable, case-insensitive --capability a plugin capability; repeatable --plugin-type a plugin socket type (for example provider, governance) -l, --selector a label selector over the entity's catalog labels
Category is matched through the label selector, not a dedicated flag: a catalogcategory is the label component.aggrega.ai/category, so'-l component.aggrega.ai/category=compute' scopes the result to that category.
With no --registry, every configured registry's index is searched and theresults are merged. With --registry (a host or a friendly alias), only thatregistry's index is searched.
A search needs at least one configured registry. With none configured there isnowhere to look, so the command refuses: the reason goes to standard error,standard output carries nothing, and the exit status is non-zero. That is whatlets a caller tell a search that ran and matched nothing from a search thatcould not be performed. Run 'aggrega config init' to register a registry withits signature trust policy, then 'aggrega registry update' to build the index.
The version reported for an entity is the one a resolution would take: aversion a publisher has retracted, where the retraction carries a signaturethis workspace's trust policy verifies, is not reported. Such an entity isstill listed, and the versions left out are named in a NOTES column, so anentity whose every published version is retracted is reported as existing withno version to take rather than disappearing from the result. Pass--include-retracted to report the highest published version whatever itsretraction status; the NOTES column names the retracted versions either way.The same holds for 'aggrega search -o json', where the 'version' field carriesthe version a resolution would take and a 'retracted' array names the versionsleft out.Flags
| Flag | Predefinição | Descrição |
|---|---|---|
--capability | [] | Capacidade de Plugin a corresponder. Repetível; é mantido um registo que declare qualquer uma delas. |
--include-retracted | false | Reportar a versão publicada mais alta mesmo onde um marcador verificado a retira. Por predefinição, a versão reportada é uma que uma resolução tomaria. |
--kind | [] | Tipo de entidade a corresponder (component|feature|recipe|featurerecipe|workload|plugin). Repetível; um registo que corresponda a qualquer um deles é mantido. Não distingue maiúsculas de minúsculas. |
--limit | 0 | Limitar o número de resultados (0 significa sem limite). |
--output, -o | table | Formato de saída: table|json|names. |
--plugin-type | — | Tipo de socket de Plugin a corresponder (por exemplo provider, governance, linter). |
--registry | — | Pesquisar apenas neste registo, indicado pelo anfitrião ou pelo alias amigável. Por predefinição, pesquisa em todos os registos configurados. |
--selector, -l | — | Seletor de etiquetas sobre as etiquetas de catálogo da entidade, que incluem a sua categoria (-l component.aggrega.ai/category=compute). |
Quando não há nenhum registo configurado
Uma pesquisa lê o índice local dos registos que esta máquina está configurada para alcançar, pelo que precisa de pelo menos um deles. Sem nenhum configurado não há onde procurar, e aggrega search recusa em vez de responder: escreve a razão no erro padrão, termina com código diferente de zero e deixa a saída padrão vazia — em todos os formatos de saída, incluindo --output json.
A recusa é o que mantém separadas duas respostas diferentes. Uma pesquisa que foi executada e não encontrou nada termina com zero e reporta (no matches) na saída padrão; uma pesquisa que não pôde de todo ser executada termina com código diferente de zero e não reporta nada aí. Um script que se ramifique pelo estado de saída consegue, portanto, distinguir «esta entidade não está publicada» de «esta máquina não tem nenhum registo a quem perguntar», o que um aviso na saída padrão e um estado zero não conseguem exprimir.
Execute aggrega config init para registar um registo juntamente com a sua política de confiança de assinaturas e, depois, aggrega registry update para construir o índice local que a pesquisa lê.
aggrega registry list e aggrega registry update respondem à mesma situação de forma diferente, e deliberadamente. Listar os registos quando não há nenhum é uma listagem completa de um conjunto vazio, e uma construção de índice sem nada para percorrer não tem mais nada a fazer: ambas são operações terminadas, pelo que ambas reportam na saída padrão e terminam com zero. Só a pesquisa está a reportar que não conseguiu fazer o que lhe foi pedido.
A versão que uma pesquisa reporta
A coluna VERSION contém a versão que uma resolução tomaria. Uma versão que o seu publicador retirou não é reportada, desde que a retirada tenha uma assinatura que a política de confiança deste espaço de trabalho verifique — as mesmas duas condições que decidem se uma retirada afeta um pull, pelo que uma pesquisa e um pull concordam sobre qual versão é a resposta.
Uma retirada que falhe qualquer das condições não altera nada no que é reportado. Um marcador com uma gravidade consultiva deixa a sua versão selecionável, e um marcador cuja assinatura não é verificada não é uma afirmação sobre a qual este espaço de trabalho atue. Em ambos os casos, a versão publicada mais alta é reportada exatamente como seria sem marcador nenhum.
Uma entidade com uma versão retirada continua a ser listada. Uma coluna NOTES nomeia as versões deixadas de fora, e só aparece num resultado que tenha algo a reportar. Uma entidade cujas versões publicadas foram todas retiradas é reportada com (none) como versão e uma nota a dizer que não resta nenhuma versão, em vez de ser retirada do resultado — uma entidade omitida seria indistinguível de uma que não existe.
Passe --include-retracted para reportar a versão publicada mais alta, seja qual for o seu estado de retirada, que é a resposta a «o que está publicado?» e não a «o que devo usar?». Altera apenas a versão reportada; a coluna NOTES nomeia as versões retiradas em qualquer dos casos.
O que uma pesquisa lê é o índice local que aggrega registry update escreve, pelo que reporta o que cada registo declarava quando esse índice foi construído pela última vez. Uma versão retirada desde então ainda não está registada, e a linha de atualidade escrita no erro padrão nomeia o momento em que cada índice foi construído.
O resultado legível por máquina
--output json transporta o mesmo contrato em dois campos:
versioné a versão que uma resolução tomaria. É a cadeia vazia quando todas as versões publicadas foram retiradas, o que se combina com uma listaretractedque as nomeia todas.retractedlista as versões deixadas fora dessa escolha, por ordem crescente de versão. Está ausente quando nada foi deixado de fora.
Um consumidor que pergunte que versão obteria lê version. Derivá-la em vez disso da matriz deprecations significa reimplementar as condições de gravidade e de assinatura, e uma segunda implementação dessas condições pode discordar da que o compilador aplica; retracted reporta o resultado que essas condições já produziram.
Cada registo contém também published: todas as versões que o índice registou, por ordem crescente de versão, cada uma com o manifestDigest para que a sua tag resolveu quando o índice foi construído e, onde a política de confiança deste espaço de trabalho verificou a própria assinatura dessa versão, o seu signer — de várias que sejam verificadas, aquela que o registo de transparência registou mais cedo. Uma versão sem signer não tem nenhuma assinatura que essa política tenha verificado, e nada mais é dito sobre ela. Um consumidor que leia o conteúdo de uma versão endereça-o por esse digest — por exemplo aggrega inspect oci://<host>/<repository>@<digest> — pelo que o que lê são os bytes que o índice registou, aconteça o que acontecer à tag depois.
Onde algo regista quando uma versão foi publicada, a sua entrada contém também publishedAt, um carimbo temporal RFC 3339 em UTC ao segundo, e publishedAtSource, que indica de onde veio. transparency-log é a hora a que um registo de transparência registou a assinatura keyless da versão, que a política de confiança deste espaço de trabalho verificou juntamente com a promessa assinada do registo relativa a essa hora — a assinatura do signer, a mais antiga das que são verificadas, pelo que voltar a assinar uma versão não altera nenhuma das duas. publisher é a hora que a publicação indicou junto do que publicou, a partir do próprio relógio da máquina que publica, que nada atesta. As duas são mantidas separadas para que um consumidor que ordene por data continue a distinguir uma hora atestada de uma declarada. Uma versão sem nenhuma das duas não contém nenhuma data, e nada mais é dito sobre ela; consulte aggrega registry update para saber quando cada uma é registada.