Diese Seite wurde mit KI-Unterstützung aus dem Englischen übersetzt. Bei Abweichungen ist die englische Version maßgeblich.
Globale Flags
Globale Flags werden von StackQL-Befehlen akzeptiert, manche gelten jedoch nur für einen bestimmten Modus. Setzen Sie sie auf der Kommandozeile oder, sofern unterstützt, in der StackQL-Initialisierungsdatei (.stackqlrc). Die --pgsrv.*-Flags sind unter PostgreSQL-Serveroptionen aufgeführt.
| Flag | Datentyp | Beschreibung | Standard |
|---|---|---|---|
--access.config | string | Konfiguration des Aufruferzugriffs, ein JSON-Envelope {"path": "/path/to/access.json"} (ein bloßer Dateipfad wird ebenfalls akzeptiert). Aktiviert die Zugriffsverwaltung: Aufrufer werden per JWT, statischem Bearer-Token, Mutual TLS oder lokaler OS-Identität authentifiziert und Anweisungen anhand von Policy-Regeln autorisiert. Lokale Token-Anmeldedaten werden aus STACKQL_CALLER_TOKEN gelesen. Verfügbar in StackQL-Releases ab v1.0. | |
--allow-persistent-secrets | flag | Erlaubt einer Sitzung, mit SET "$.secret_store" einen persistenten OS-Secret-Store (macOS Keychain, Linux Secret Service oder Windows Credential Manager) auszuwählen. Flat-File-Stores werden auch mit dem Flag verweigert. Siehe Provider-Sitzungen und Secrets. Verfügbar in StackQL-Releases ab v1.0. | false |
--allow-secret-dereference | flag | Erlaubt das Dereferenzieren von Secret- und Anmeldedatenwerten in SQL-Ausdrücken ("$secrets.name", "$auth.provider.field"), mit der Folge, dass sie in Ergebnisse, Logs und persistierte Abfrageartefakte gelangen können. Für die normale Provider-Authentifizierung nicht erforderlich. Siehe Secret-Werte in SQL. Verfügbar in StackQL-Releases ab v1.0. | false |
--apirequesttimeout | integer | Timeout für API-Anfragen in Sekunden, 0 für kein Timeout | 45 |
--approot | string | Wurzelpfad für Anwendungskonfiguration und Cache | {cwd}/.stackql |
--approotfilemode | uint32 | Dateimodus für Anwendungskonfiguration und Cache | 493 |
--auth | string | auth-Kontext-Schlüssel-Wert-Paare in json-Form | |
--cachekeycount | integer | Anfängliche Schlüsselanzahl des Caches | 100 |
--configfile | string | Vollständiger Pfad der Konfigurationsdatei | {cwd}/.stackqlrc |
--cpuprofile | string | cpuprofile-Datei, keine wenn leer | null |
--dataflow.dependency.max | int | Maximale Tiefe der Datenflussabhängigkeiten für eine Abfrage | 50 |
--dataflow.components.max | int | Maximale Anzahl schwach zusammenhängender Datenflusskomponenten für eine Abfrage | 50 |
--dbInternal | string | JSON-/YAML-String zur Konfiguration der Behandlung von DBMS-Housekeeping-Abfragen | {} |
-d, --delimiter | string | Trennzeichen für die csv-Ausgabe. Nur ein einzelnes Zeichen. Wird bei jeder Nicht-csv-Ausgabe ignoriert | , |
--dryrun | flag | dryrun-Flag; nur den Präprozessor ausführen, die templatierte Ausgabe wird zurückgegeben | false |
--env.file | string | Optionale Datei im dotenv-Stil, die beim Start in die Prozessumgebung eingelesen wird (alle Befehle); das MCP-Tool reload_credentials liest sie bei Bedarf erneut ein. Eine fehlende Datei wird toleriert; Schlüssel mit leeren Werten werden übersprungen; vorhandene Variablen werden überschrieben. Wird nicht aus .stackqlrc gelesen. Verfügbar in StackQL-Releases nach v0.10.542. | null |
--execution.concurrency.limit | int | Parallelitätslimit für die Abfrageausführung | 1 |
--export.alias | string | Präfix für Export-Aliase (Namespace oder Schema) | |
--gc | string | JSON-/YAML-String mit der GC-Konfiguration | {} |
-H, --hideheaders | flag | Deaktiviert Spaltenüberschriften, nur gültig mit --output csv oder --output text | false |
--http.log.enabled | flag | Zeigt http-Anfrageinformationen im Terminal an | false |
--http.proxy.host | string | Proxy-Host (leer lassen für keinen Proxy) | null |
--http.proxy.password | string | Proxy-Passwort | null |
--http.proxy.port | integer | Proxy-Port, jede Zahl kleiner oder gleich 0 führt zum Standardport des jeweiligen Schemas (z. B. http -> 80) | -1 |
--http.proxy.scheme | string | Proxy-Schema, http oder https | http |
--http.proxy.user | string | Proxy-Benutzer | null |
--http.response.maxResults | integer | Maximale Ergebnisse pro http-Anfrage, jede Zahl kleiner oder gleich 0 bedeutet keine Begrenzung | -1 |
--http.response.pageLimit | integer | Maximale Anzahl von Ergebnisseiten, die pro Ressource zurückgegeben werden, jede Zahl kleiner oder gleich 0 bedeutet keine Begrenzung | 20 |
--indirect.depth.max | integer | Maximale Tiefe für indirekte Abfragen: Views und Unterabfragen | 5 |
-i, --infile | string | Eingabedatei (IQL-Datei), aus der Abfragen gelesen werden | {stdin} |
-q, --iqldata | string | Kontextdatei (Daten) für das Templating (json- oder jsonnet-Datei) | |
--loglevel | string | Log-Level, muss einer von {panic, fatal, error, warn, info, debug, trace} sein (warning wird als Alias für warn akzeptiert) | fatal |
--mcp.config | string | JSON-/YAML-Konfigurationsobjekt für den MCP-Server (stackql mcp und stackql srv) | {} |
--mcp.log.format | string | Kodierung des MCP-Audit-Logs, jsonl oder otel (OTLP/JSON-Log-Records); überschreibt server.audit.format in --mcp.config. Siehe Log-Format. Verfügbar in StackQL-Releases ab v0.11.660. | jsonl |
--mcp.protocol.version | string | Neueste angekündigte MCP-Protokollrevision, auto, 2026-07-28 (nur sitzungslos) oder eine ältere Revision wie 2025-11-25; überschreibt server.protocol_version in --mcp.config. Siehe Festlegen der Revision. Verfügbar in StackQL-Releases ab v0.12.732. | auto |
--mcp.server.type | string | MCP-Servertyp, einer von {http, stdio, reverse_proxy}. Siehe MCP-Servertyp. | http |
--metadatattl | integer | TTL für zwischengespeicherte Metadatendokumente, in Sekunden | 3600 |
--namespaces | string | JSON-/YAML-String mit Namespaces für Caching, Views usw. | {} |
--offline | flag | Offline arbeiten, mit zwischengespeicherten Daten | false |
-f, --outfile | string | Ausgabedatei, in die Ergebnisse geschrieben werden | {stdout} |
-o, --output | string | Ausgabeformat, muss eines von {json, jsonl, table, csv, text, otel} sein (ndjson wird als Alias für jsonl akzeptiert). otel gibt OpenTelemetry-Log-Records aus, siehe Ausgabemodi; verfügbar in StackQL-Releases ab v0.11.660. Ist in --otel.config ein Exporter konfiguriert, werden otel-Records zusätzlich an diesen Endpunkt gesendet | table |
--otel.config | string | JSON-/YAML-String zur Konfiguration des Ausgabeformats otel; exporter.endpoint, exporter.headers, exporter.timeout_ms und exporter.batch_size senden die Records an einen OTLP/HTTP-Logs-Endpunkt, siehe Push an einen OTLP-Endpunkt. Verfügbar in StackQL-Releases ab v0.12.732 | {} |
--preview | string | JSON-String zur Aktivierung von Preview-Funktionen. {"unstable": true} stellt die dokumentgetriebenen Relationen stackql_unstable_<provider>.<service>.<resource> bereit, die von omnisdk direkt aus den Provider-Dokumenten aufgelöst und ausgeführt werden, wobei Zeilen gestreamt werden, sobald sie entstehen; die übrigen Schlüssel (batchSize, flushInterval, endpoint, insecureSkipTLSVerify) stimmen dieses Backend ab. Preview-Funktionen sind nicht stabil: Verhalten, Syntax und Ausgabe können sich zwischen Releases ohne Ankündigung ändern oder brechen, verlassen Sie sich daher in der Produktion nicht darauf. Ab v1.0 stellt dasselbe Opt-in die Relationen stackql_preview.iac.run und stackql_preview.iac.destroy bereit, die eine deklarierte Ressourcenmenge über omnisdk anwenden und abbauen, wobei der Zustand unter dem Anwendungswurzelpfad gehalten wird. Siehe Preview-Funktionen | {} |
--provider | string | Anfänglicher Standard-Provider. Mit --provider github wird beispielsweise repos.repos ohne vorangehende USE-Anweisung zu github.repos.repos aufgelöst. Authentifiziert nicht beim Provider. | keiner |
--querycachesize | integer | Größe des LRU-Caches für Abfragepläne in Anzahl der Einträge | 10000 |
--registry | string | JSON-/YAML-String zur Konfiguration des Speicherorts der Provider-Registry und der Signaturprüfung von Provider-Dokumenten | siehe --registry |
--session | string | JSON-/YAML-String mit der Sitzungskonfiguration | {} |
--sqlBackend | string | JSON-/YAML-String mit der Systemkonfiguration des SQL-Backends | siehe --sqlBackend |
--store.txn | string | JSON-/YAML-String mit der Konfiguration des Txn-Stores | {} |
--tls.CABundle | string | Pfad zum CA-Bundle, ohne Angabe werden die Systemstandards verwendet | |
--tls.allowInsecure | flag | Erlaubt das Vertrauen in unsichere Zertifikate (nicht empfohlen) | |
--upstream.errors | string | JSON-/YAML-Richtlinie, um HTTP-Antwortstatus bei Provider-Lesezugriffen explizit zu tolerieren. Siehe --upstream.errors. | {} |
--var | string | Externe Variablen als Schlüssel/Wert-Paare, die über jsonnet-Datendateien in StackQL-Abfragen eingelesen werden | |
-v, --verbose | flag | Ausführliche Ausgabe | false |
-h, --help | Kontextspezifische Hilfe für stackql | ||
--version | Zeigt die Version des StackQL-Programms an |
--colorscheme ist veraltet und ändert die Farben der Shell nicht mehr. --usenonpreferredapis wird akzeptiert, ändert in der aktuellen Engine aber nicht die API-Auswahl.
--registry
Das Flag --registry konfiguriert, woher Provider-Dokumente gelesen werden und ob ihre Signaturen geprüft werden. Der Wert ist ein JSON-String mit den folgenden Schlüsseln:
| Schlüssel | Beschreibung | Standard |
|---|---|---|
url | Registry-URL. Ohne Angabe wird die öffentliche StackQL-Provider-Registry verwendet. | öffentliche Registry |
localDocRoot | Ein lokales Verzeichnis mit Provider-Dokumenten, das anstelle eines Downloads aus der Registry gelesen wird. Wird beim Entwickeln eines Providers verwendet. | |
srcPrefix | Pfadpräfix unterhalb der Registry-Wurzel, in dem die Provider-Quelldokumente liegen. | src |
verifyConfig.nopVerify | true überspringt die Signaturprüfung. Auf false setzen, um für jedes gelesene Provider- und Service-Dokument eine eingebettete ML-DSA-65-Signatur (FIPS 204) zu verlangen, einschließlich der dokumentgestützten Preview-Relationen. | true |
verifyConfig.publicKeys | Ein JSON-Objekt, das Schlüssel-IDs auf hex-kodierte öffentliche ML-DSA-65-Schlüssel abbildet, für private Registries. Es ersetzt die eingebetteten Produktionsschlüssel; ein explizit leeres Objekt ist ein Fehler. | eingebettete Schlüssel |
Beispiel: Signierte Provider-Dokumente verlangen
Schaltet die Prüfung für jedes aus der öffentlichen Registry gelesene Provider- und Service-Dokument ein, geprüft gegen die eingebetteten Produktionsschlüssel:
stackql --registry '{"verifyConfig": {"nopVerify": false}}' shell
Beispiel: Unsignierte Dokumente aus einem lokalen Verzeichnis lesen
Verweist die Registry auf ein Verzeichnis mit Provider-Dokumenten in Entwicklung. Diese Dokumente sind unsigniert, daher bleibt die Prüfung ausgeschaltet:
stackql --registry '{"localDocRoot": "/path/to/provider-dev/openapi", "verifyConfig": {"nopVerify": true}}' shell
Die Signaturprüfung ist in StackQL-Releases ab v1.0 verfügbar und standardmäßig ausgeschaltet. Signaturen decken die exakten YAML-Bytes eines Dokuments ab, sodass jede Änderung, auch eine Formatierungs- oder Zeilenumbruchänderung, sie ungültig macht; signieren Sie mit dem Tool pqsig sign-doc der Registry neu. Unsignierte lokale Entwicklungsdokumente müssen nopVerify: true beibehalten. Die früheren Zertifikatsoptionen und .sig-Sidecar-Dateien werden nicht mehr verwendet, und Archive, die nur mit Sidecars veröffentlicht wurden, müssen vor einer geprüften Verwendung neu veröffentlicht werden. Die Prüfung authentifiziert Dokumente beim Lesen; Download und Entpacken von Archiven sind nicht abgedeckt.
--sqlBackend
Das Flag --sqlBackend konfiguriert ein externes SQL-Backend für StackQL, sodass Sie anstelle der standardmäßig eingebetteten SQL-Engine eine externe Datenbank-Engine (etwa PostgreSQL) verwenden können. Das ist nützlich, um eine externe Datenbank für die Abfrageverarbeitung, persistente Speicherung oder die Integration in bestehende Datenbankinfrastruktur zu nutzen.
Der Wert ist ein JSON-String mit den folgenden Schlüsseln:
| Schlüssel | Beschreibung | Beispielwerte |
|---|---|---|
dbEngine | Der Typ der Datenbank-Engine | postgres_tcp |
sqlDialect | Der zu verwendende SQL-Dialekt | postgres |
dsn | Der Data Source Name (Verbindungszeichenfolge) der Datenbank | Siehe Beispiele unten |
Beispiel: Ein PostgreSQL-Backend verwenden
./stackql \
--sqlBackend='{"dbEngine": "postgres_tcp", "sqlDialect": "postgres", "dsn": "postgres://user:password@hostname:port/dbname?sslmode=require"}' \
shell
Beispiel: Die PostgreSQL-Schnittstelle von Databricks verwenden
Databricks stellt eine PostgreSQL-kompatible Schnittstelle bereit, die als StackQL-SQL-Backend verwendet werden kann. Der DSN verwendet das Standardformat der PostgreSQL-Verbindungszeichenfolge mit Ihren Databricks-Anmeldedaten:
./stackql \
--sqlBackend='{"dbEngine": "postgres_tcp", "sqlDialect": "postgres", "dsn": "postgres://user%40domain.com:your-access-token@your-databricks-host.cloud.databricks.com/databricks_postgres?sslmode=require"}' \
shell
Sonderzeichen im Benutzernamen oder Passwort (etwa @) müssen im DSN URL-kodiert sein (z. B. wird aus @ %40).
--upstream.errors
Listen Sie mit http.ignoreStatusCodes die HTTP-Antwortstatus auf, die ein Provider-Lesezugriff explizit tolerieren soll. Die Einträge sind Strings: Verwenden Sie einen exakten Code wie "503" oder eine Klasse wie "5xx". Der Standardwert {} fügt der normalen Behandlung von Upstream-Antworten durch die Engine keine Ausnahmen hinzu. Diese Einstellung wiederholt keine fehlgeschlagenen Anfragen und gilt nicht für Mutationen oder Authentifizierungsvorgänge.
Eine ignorierte Antwort trägt keine Zeilen bei. Andere Lesezugriffe in der Abfrage können weiterhin Zeilen zurückgeben, sodass eine erfolgreiche Abfrage unvollständige Ergebnisse liefern kann. StackQL meldet den ignorierten HTTP-Status als Diagnose.
Beispielsweise verwendet der gemockte GitHub-Join-Test diese Option:
stackql exec --upstream.errors='{"http":{"ignoreStatusCodes":["5xx"]}}' \
"SELECT r.name, c.login FROM github.repos.repos r
JOIN github.repos.collaborators c ON c.repo = r.name
WHERE r.org = 'example-org' AND c.owner = 'example-org'
ORDER BY r.name;"
Im Test gibt die Collaborators-Anfrage für ein Repository HTTP 500 zurück. Die Abfrage liefert weiterhin Collaborator-Zeilen für die anderen Repositories, und stderr enthält ignoring upstream response: 500 INTERNAL SERVER ERROR. Bevorzugen Sie einen exakten Statuscode, wenn nur ein Fehler erwartet wird.