aggrega search
Den lokalen Index der konfigurierten Registries durchsuchen
Übersicht
aggrega search [query] [flags]Beschreibung
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 | Standard | Beschreibung |
|---|---|---|
--capability | [] | Abzugleichende Plugin-Fähigkeit. Wiederholbar; ein Datensatz, der eine beliebige davon deklariert, wird behalten. |
--include-retracted | false | Meldet die höchste veröffentlichte Version auch dort, wo ein verifizierter Marker sie zurückzieht. Standardmäßig ist die gemeldete Version diejenige, die eine Auflösung wählen würde. |
--kind | [] | Abzugleichende Entitätsart (component|feature|recipe|featurerecipe|workload|plugin). Wiederholbar; ein Datensatz, der einer beliebigen davon entspricht, wird behalten. Groß-/Kleinschreibung wird nicht beachtet. |
--limit | 0 | Begrenzt die Anzahl der Ergebnisse (0 bedeutet keine Begrenzung). |
--output, -o | table | Ausgabeformat: table|json|names. |
--plugin-type | — | Abzugleichender Plugin-Socket-Typ (zum Beispiel provider, governance, linter). |
--registry | — | Durchsucht nur diese Registry, adressiert über Host oder Anzeigealias. Standardmäßig wird jede konfigurierte Registry durchsucht. |
--selector, -l | — | Label-Selektor über die Katalog-Labels der Entität, zu denen ihre Kategorie gehört (-l component.aggrega.ai/category=compute). |
Wenn keine Registry konfiguriert ist
Eine Suche liest den lokalen Index der Registries, die dieser Rechner erreichen soll, und benötigt daher mindestens eine davon. Ist keine konfiguriert, gibt es nichts zu durchsuchen, und aggrega search lehnt ab, statt zu antworten: Der Befehl schreibt den Grund in die Standardfehlerausgabe, endet mit einem Status ungleich null und lässt die Standardausgabe leer — in jedem Ausgabeformat, --output json eingeschlossen.
Die Ablehnung hält zwei verschiedene Antworten auseinander. Eine Suche, die gelaufen ist und nichts gefunden hat, endet mit null und meldet (no matches) in der Standardausgabe; eine Suche, die gar nicht laufen konnte, endet mit einem Status ungleich null und meldet dort nichts. Ein Skript, das anhand des Exit-Status verzweigt, kann daher „diese Entität ist nicht veröffentlicht“ von „dieser Rechner hat keine Registry, die er fragen kann“ unterscheiden, was ein Hinweis in der Standardausgabe zusammen mit einem Status null nicht ausdrücken kann.
Führen Sie aggrega config init aus, um eine Registry zusammen mit ihrer Signatur-Vertrauensrichtlinie zu registrieren, und dann aggrega registry update, um den lokalen Index zu erstellen, den die Suche liest.
aggrega registry list und aggrega registry update beantworten dieselbe Situation anders, und zwar bewusst. Registries aufzulisten, wenn es keine gibt, ist eine vollständige Auflistung einer leeren Menge, und ein Index-Build ohne etwas zu durchlaufen hat nichts mehr zu tun: Beides sind abgeschlossene Vorgänge, daher melden beide in der Standardausgabe und enden mit null. Nur die Suche meldet, dass sie nicht tun konnte, worum sie gebeten wurde.
Die Version, die eine Suche meldet
Die Spalte VERSION enthält die Version, die eine Auflösung wählen würde. Eine Version, die ihr Herausgeber zurückgezogen hat, wird nicht gemeldet, sofern der Rückzug eine Signatur trägt, die die Vertrauensrichtlinie dieses Workspace verifiziert — dieselben zwei Bedingungen, die entscheiden, ob ein Rückzug einen Pull betrifft, sodass eine Suche und ein Pull darin übereinstimmen, welche Version die Antwort ist.
Ein Rückzug, der eine der beiden Bedingungen nicht erfüllt, ändert nichts an dem, was gemeldet wird. Ein Marker mit beratendem Schweregrad lässt seine Version auswählbar, und ein Marker, dessen Signatur sich nicht verifizieren lässt, ist keine Aussage, nach der dieser Workspace handelt. In beiden Fällen wird die höchste veröffentlichte Version genau so gemeldet, wie sie ohne jeden Marker gemeldet würde.
Eine Entität mit einer zurückgezogenen Version wird weiterhin aufgeführt. Eine Spalte NOTES nennt die ausgelassenen Versionen und erscheint nur in einem Ergebnis, das etwas zu melden hat. Eine Entität, deren sämtliche veröffentlichten Versionen zurückgezogen sind, wird mit (none) als Version und einem Hinweis gemeldet, dass keine Version übrig bleibt, statt aus dem Ergebnis entfernt zu werden — eine ausgelassene Entität wäre von einer nicht existierenden nicht zu unterscheiden.
Übergeben Sie --include-retracted, um die höchste veröffentlichte Version unabhängig von ihrem Rückzugsstatus zu melden; das ist die Antwort auf „Was ist veröffentlicht?“ statt auf „Was sollte ich verwenden?“. Es ändert nur die gemeldete Version; die Spalte NOTES nennt die zurückgezogenen Versionen in beiden Fällen.
Eine Suche liest den lokalen Index, den aggrega registry update schreibt, und meldet daher, was jede Registry angegeben hat, als dieser Index zuletzt erstellt wurde. Eine seitdem zurückgezogene Version ist noch nicht erfasst, und die in die Standardfehlerausgabe geschriebene Aktualitätszeile nennt den Zeitpunkt, zu dem jeder Index erstellt wurde.
Das maschinenlesbare Ergebnis
--output json bildet denselben Vertrag in zwei Feldern ab:
versionist die Version, die eine Auflösung wählen würde. Sie ist die leere Zeichenkette, wenn jede veröffentlichte Version zurückgezogen ist, und geht dann mit einerretracted-Liste einher, die sie alle nennt.retractedlistet die von dieser Wahl ausgelassenen Versionen in aufsteigender Versionsreihenfolge auf. Das Feld fehlt, wenn nichts ausgelassen wurde.
Ein Konsument, der wissen will, welche Version er erhalten würde, liest version. Dies stattdessen aus dem Array deprecations abzuleiten, bedeutet, die Bedingungen zu Schweregrad und Signatur neu zu implementieren, und eine zweite Implementierung dieser Bedingungen kann durchaus von der abweichen, die der Compiler anwendet; retracted meldet das Ergebnis, das diese Bedingungen bereits geliefert haben.
Jeder Datensatz enthält außerdem published: jede Version, die der Index erfasst hat, in aufsteigender Versionsreihenfolge, jeweils mit dem manifestDigest, zu dem ihr Tag beim Erstellen des Index aufgelöst wurde, und, wo die Vertrauensrichtlinie dieses Workspace die eigene Signatur dieser Version verifiziert hat, ihrem signer — von mehreren, die sich verifizieren lassen, derjenige, den das Transparenzprotokoll am frühesten erfasst hat. Eine Version ohne signer trägt keine Signatur, die diese Richtlinie verifiziert hat, und mehr wird über sie nicht gesagt. Ein Konsument, der den Inhalt einer Version liest, adressiert ihn über diesen Digest — zum Beispiel aggrega inspect oci://<host>/<repository>@<digest> —, sodass er die Bytes liest, die der Index erfasst hat, unabhängig davon, was danach mit dem Tag geschieht.
Wo etwas festhält, wann eine Version veröffentlicht wurde, enthält ihr Eintrag außerdem publishedAt, einen RFC-3339-Zeitstempel in UTC auf die Sekunde genau, und publishedAtSource, das angibt, woher er stammt. transparency-log ist der Zeitpunkt, zu dem ein Transparenzprotokoll die schlüssellose Signatur der Version erfasst hat, die die Vertrauensrichtlinie dieses Workspace zusammen mit der signierten Zusicherung des Protokolls über diesen Zeitpunkt verifiziert hat — die Signatur des signer, die früheste der sich verifizierenden, sodass ein erneutes Signieren einer Version keines von beiden verschiebt. publisher ist der Zeitpunkt, den die Veröffentlichung neben dem Veröffentlichten angegeben hat, nach der eigenen Uhr des veröffentlichenden Rechners, die nichts bestätigt. Die beiden werden getrennt gehalten, damit ein Konsument, der nach Datum sortiert, eine bestätigte Zeit weiterhin von einer angegebenen unterscheiden kann. Eine Version ohne beides trägt kein Datum, und mehr wird über sie nicht gesagt; unter aggrega registry update steht, wann jedes davon erfasst wird.