Zum Hauptinhalt springen
Übersetzte Seite

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.

FlagDatentypBeschreibungStandard
--access.configstringKonfiguration 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-secretsflagErlaubt 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-dereferenceflagErlaubt 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
--apirequesttimeoutintegerTimeout für API-Anfragen in Sekunden, 0 für kein Timeout45
--approotstringWurzelpfad für Anwendungskonfiguration und Cache{cwd}/.stackql
--approotfilemodeuint32Dateimodus für Anwendungskonfiguration und Cache493
--authstringauth-Kontext-Schlüssel-Wert-Paare in json-Form
--cachekeycountintegerAnfängliche Schlüsselanzahl des Caches100
--configfilestringVollständiger Pfad der Konfigurationsdatei{cwd}/.stackqlrc
--cpuprofilestringcpuprofile-Datei, keine wenn leernull
--dataflow.dependency.maxintMaximale Tiefe der Datenflussabhängigkeiten für eine Abfrage50
--dataflow.components.maxintMaximale Anzahl schwach zusammenhängender Datenflusskomponenten für eine Abfrage50
--dbInternalstringJSON-/YAML-String zur Konfiguration der Behandlung von DBMS-Housekeeping-Abfragen{}
-d, --delimiterstringTrennzeichen für die csv-Ausgabe. Nur ein einzelnes Zeichen. Wird bei jeder Nicht-csv-Ausgabe ignoriert,
--dryrunflagdryrun-Flag; nur den Präprozessor ausführen, die templatierte Ausgabe wird zurückgegebenfalse
--env.filestringOptionale 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.limitintParallelitätslimit für die Abfrageausführung1
--export.aliasstringPräfix für Export-Aliase (Namespace oder Schema)
--gcstringJSON-/YAML-String mit der GC-Konfiguration{}
-H, --hideheadersflagDeaktiviert Spaltenüberschriften, nur gültig mit --output csv oder --output textfalse
--http.log.enabledflagZeigt http-Anfrageinformationen im Terminal anfalse
--http.proxy.hoststringProxy-Host (leer lassen für keinen Proxy)null
--http.proxy.passwordstringProxy-Passwortnull
--http.proxy.portintegerProxy-Port, jede Zahl kleiner oder gleich 0 führt zum Standardport des jeweiligen Schemas (z. B. http -> 80)-1
--http.proxy.schemestringProxy-Schema, http oder httpshttp
--http.proxy.userstringProxy-Benutzernull
--http.response.maxResultsintegerMaximale Ergebnisse pro http-Anfrage, jede Zahl kleiner oder gleich 0 bedeutet keine Begrenzung-1
--http.response.pageLimitintegerMaximale Anzahl von Ergebnisseiten, die pro Ressource zurückgegeben werden, jede Zahl kleiner oder gleich 0 bedeutet keine Begrenzung20
--indirect.depth.maxintegerMaximale Tiefe für indirekte Abfragen: Views und Unterabfragen5
-i, --infilestringEingabedatei (IQL-Datei), aus der Abfragen gelesen werden{stdin}
-q, --iqldatastringKontextdatei (Daten) für das Templating (json- oder jsonnet-Datei)
--loglevelstringLog-Level, muss einer von {panic, fatal, error, warn, info, debug, trace} sein (warning wird als Alias für warn akzeptiert)fatal
--mcp.configstringJSON-/YAML-Konfigurationsobjekt für den MCP-Server (stackql mcp und stackql srv){}
--mcp.log.formatstringKodierung 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.versionstringNeueste 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.typestringMCP-Servertyp, einer von {http, stdio, reverse_proxy}. Siehe MCP-Servertyp.http
--metadatattlintegerTTL für zwischengespeicherte Metadatendokumente, in Sekunden3600
--namespacesstringJSON-/YAML-String mit Namespaces für Caching, Views usw.{}
--offlineflagOffline arbeiten, mit zwischengespeicherten Datenfalse
-f, --outfilestringAusgabedatei, in die Ergebnisse geschrieben werden{stdout}
-o, --outputstringAusgabeformat, 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 gesendettable
--otel.configstringJSON-/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{}
--previewstringJSON-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{}
--providerstringAnfä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
--querycachesizeintegerGröße des LRU-Caches für Abfragepläne in Anzahl der Einträge10000
--registrystringJSON-/YAML-String zur Konfiguration des Speicherorts der Provider-Registry und der Signaturprüfung von Provider-Dokumentensiehe --registry
--sessionstringJSON-/YAML-String mit der Sitzungskonfiguration{}
--sqlBackendstringJSON-/YAML-String mit der Systemkonfiguration des SQL-Backendssiehe --sqlBackend
--store.txnstringJSON-/YAML-String mit der Konfiguration des Txn-Stores{}
--tls.CABundlestringPfad zum CA-Bundle, ohne Angabe werden die Systemstandards verwendet
--tls.allowInsecureflagErlaubt das Vertrauen in unsichere Zertifikate (nicht empfohlen)
--upstream.errorsstringJSON-/YAML-Richtlinie, um HTTP-Antwortstatus bei Provider-Lesezugriffen explizit zu tolerieren. Siehe --upstream.errors.{}
--varstringExterne Variablen als Schlüssel/Wert-Paare, die über jsonnet-Datendateien in StackQL-Abfragen eingelesen werden
-v, --verboseflagAusführliche Ausgabefalse
-h, --helpKontextspezifische Hilfe für stackql
--versionZeigt 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üsselBeschreibungStandard
urlRegistry-URL. Ohne Angabe wird die öffentliche StackQL-Provider-Registry verwendet.öffentliche Registry
localDocRootEin lokales Verzeichnis mit Provider-Dokumenten, das anstelle eines Downloads aus der Registry gelesen wird. Wird beim Entwickeln eines Providers verwendet.
srcPrefixPfadpräfix unterhalb der Registry-Wurzel, in dem die Provider-Quelldokumente liegen.src
verifyConfig.nopVerifytrue ü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.publicKeysEin 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
hinweis

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üsselBeschreibungBeispielwerte
dbEngineDer Typ der Datenbank-Enginepostgres_tcp
sqlDialectDer zu verwendende SQL-Dialektpostgres
dsnDer Data Source Name (Verbindungszeichenfolge) der DatenbankSiehe 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

hinweis

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.