Daten aus Timestream für InfluxDB 3 abfragen

Amazon Timestream for InfluxDB 3 bietet mehrere Abfragen APIs und Protokolle zum Abrufen Ihrer Zeitreihendaten. Die Plattform unterstützt sowohl SQL- als auch InfluxQL-Abfragesprachen über die Protokolle HTTP and Flight (gRPC) und bietet Flexibilität für unterschiedliche Anwendungsfälle und Kundenpräferenzen.

Übersicht über die Abfragemethoden

InfluxDB 3 unterstützt die folgenden Abfragemethoden:

• Native v3-HTTP-API — SQL- und InfluxQL-Abfragen über REST-Endpunkte.

• influxdb3 CLI — Befehlszeilenschnittstelle für interaktive Abfragen.

• Flight+gRPC Protocol — Leistungsstarkes Binärprotokoll für Client-Bibliotheken.

• v1-Kompatibilitäts-API — Legacy-InfluxQL-Abfragen für Abwärtskompatibilität.

Verwenden der v3-HTTP-Abfrage-API

Die v3-API bietet spezielle Endpunkte für SQL- und InfluxQL-Abfragen mit Unterstützung sowohl für GET- als auch für POST-Methoden.

SQL-Abfragen () /api/v3/query_sql

Beispiel für eine GET-Anfrage:

curl --get "https://your-cluster-endpoint:8086/api/v3/query_sql" \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode "db=DATABASE_NAME" \
  --data-urlencode "q=SELECT * FROM home WHERE time >= now() - INTERVAL '1 day'"

Beispiel für eine POST-Anforderung (für komplexe Abfragen):

curl "https://your-cluster-endpoint:8086/api/v3/query_sql" \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --json '{
    "db": "DATABASE_NAME",
    "q": "SELECT * FROM home WHERE room = '\''Kitchen'\'' AND temp > 20",
    "format": "jsonl"
  }'

InfluxQL-Abfragen () /api/v3/query_influxql

Gehen Sie für InfluxQL-Abfragen wie folgt vor:

curl --get "https://your-cluster-endpoint:8086/api/v3/query_influxql" \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode "db=DATABASE_NAME" \
  --data-urlencode "q=SELECT mean(temp) FROM home WHERE time >= now() - 1d GROUP BY room"

Abfrageparameter

Sie können die folgenden Abfrageparameter verwenden:

Parameter	Beschreibung	Erforderlich
db	Datenbankname	Ja
q	Abfragezeichenfolge (SQL oder InfluxQL)	Ja
format	Antwortformat (json, jsonl, csv, pretty, parquet)	Nein (Standard: json)
params	Parameter für parametrisierte Abfragen	Nein

Verwenden der Influxdb3-CLI

Die InfluxDB 3-Befehlszeilenschnittstelle (CLI) wird mit dem Befehl aufgerufen. influxdb3 Es bietet eine interaktive Möglichkeit, Ihre Daten mit Unterstützung für mehrere Ausgabeformate abzufragen.

Im Folgenden wird eine grundlegende Abfrage gezeigt:

influxdb3 query \
  --host "your-cluster-endpoint:8086" \
  --token "YOUR_TOKEN" \
  --database "DATABASE_NAME" \
  "SELECT * FROM home WHERE time >= now() - INTERVAL '1 day'"

Im Folgenden wird eine Abfrage mit unterschiedlichen Ausgabeformaten gezeigt:

# JSON output
influxdb3 query \
  --database "DATABASE_NAME" \
  --format json \
  "SELECT * FROM home LIMIT 10"

# CSV output
influxdb3 query \
  --database "DATABASE_NAME" \
  --format csv \
  "SELECT * FROM home LIMIT 10"

# Parquet file output
influxdb3 query \
  --database "DATABASE_NAME" \
  --format parquet \
  --output results.parquet \
  "SELECT * FROM home"

Die folgenden Ausgabeformate werden unterstützt:

• pretty (Standard) — Für Menschen lesbares Tabellenformat.

• json — Standard-JSON-Array.

• jsonl — JSON-Zeilen (Streaming-freundlich).

• csv — Kommagetrennte Werte.

• parquet — Binäres Spaltenformat (erfordert Dateiausgabe).

Verwenden der v1-Kompatibilitäts-API

Verwenden Sie für ältere InfluxQL-Abfragen den /query Endpunkt:

curl --get "https://your-cluster-endpoint:8086/query" \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode "db=DATABASE_NAME" \
  --data-urlencode "q=SELECT * FROM home" \
  --data-urlencode "epoch=ms"

Authentifizierungsoptionen für die v3-HTTP-Abfrage-API

• Inhaber-Token: Authorization: Bearer TOKEN

• Grundlegende Authentifizierung: --user "any:TOKEN"

• Abfrageparameter: ?p=TOKEN

Antwortformate für die v3-HTTP-Abfrage-API

• JSON (Standard)

• CSV (mit Accept: application/csv Header)

Beispiele für SQL-Abfragen

Im Folgenden wird eine einfache Abfrage gezeigt:

-- Select specific fields with time filter
SELECT temp, humidity, room 
FROM home 
WHERE time >= now() - INTERVAL '7 days'
  AND room = 'Kitchen'
ORDER BY time DESC

-- Show all tables in database
SHOW TABLES

-- Show columns in a table
SHOW COLUMNS FROM home

Im Folgenden werden Aggregationsabfragen gezeigt:

-- Aggregate by tags
SELECT 
  room,
  AVG(temp) as avg_temp,
  MAX(humidity) as max_humidity
FROM home
WHERE time >= now() - INTERVAL '24 hours'
GROUP BY room

-- Time-based aggregation using DATE_BIN
SELECT
  DATE_BIN(INTERVAL '1 hour', time) as time,
  AVG(temp) as avg_temp,
  COUNT(*) as reading_count
FROM home
GROUP BY 1
ORDER BY time DESC

Im Folgenden werden erweiterte SQL-Funktionen gezeigt:

-- Parameterized queries (via API)
SELECT * FROM home 
WHERE room = $room 
  AND temp > $min_temp
  AND time >= $start_time

-- Gap filling with interpolation
SELECT
  date_bin_gapfill(INTERVAL '5 minutes', time) as time,
  room,
  interpolate(avg(temp)) as temp
FROM home
WHERE time >= '2025-01-01T00:00:00Z' 
  AND time <= '2025-01-01T12:00:00Z'
GROUP BY 1, room

-- Type casting
SELECT 
  temp::INTEGER as temp_int,
  CAST(humidity AS VARCHAR) as humidity_str
FROM home

Im Folgenden werden Beispiele für InfluxQL-Abfragen gezeigt:

-- Basic query with time filter
SELECT * FROM home WHERE time >= now() - 1d

-- Aggregation with GROUP BY time
SELECT MEAN(temp), MAX(humidity) 
FROM home 
WHERE time >= now() - 7d 
GROUP BY time(1h), room

-- Using selector functions
SELECT FIRST(temp), LAST(temp) 
FROM home 
WHERE time >= now() - 1h 
GROUP BY room

Im Folgenden wird gezeigt, wie Sie Systemtabellen abfragen, um Ihre Datenbankstruktur zu verstehen und die Leistung zu überwachen:

-- View all tables with schema information
SELECT * FROM information_schema.tables

-- View column details for a specific table
SELECT * FROM information_schema.columns 
WHERE table_name = 'home'

-- Monitor recent queries
SELECT * FROM system.queries 
ORDER BY issue_time DESC 
LIMIT 10

-- Check cache configurations
SELECT * FROM system.last_caches
SELECT * FROM system.distinct_caches

Bewährte Methoden zur Abfrageleistung

• Verwenden Sie Zeitfilter: Verwenden Sie immer Zeitbereichsfilter, um die gescannten Daten einzuschränken.

• Nutzen Sie Indizes: Entwerfen Sie Abfragen, um Tag-Filter effektiv zu nutzen.

• Wählen Sie das passende Ausgabeformat:

  • Verwenden Sie jsonl zum Streamen großer Ergebnisse.

  • Verwenden Sie Parquet für den Datenexport und die Analyse.

  • Verwenden Sie CSV für die Kompatibilität mit Tabellenkalkulationen.

• Aggregationen optimieren: Verwenden Sie DATE_BIN für die zeitbasierte Gruppierung.

• Verwenden Sie parametrisierte Abfragen: Verhindern Sie Injection-Angriffe und verbessern Sie die Wiederverwendbarkeit.

• Überwachen Sie die Abfrageleistung: Überprüfen Sie die Tabelle system.queries auf langsame Abfragen.

Unterstützung für Abfragen in der Clientbibliothek

InfluxDB 3-Clientbibliotheken verwenden das Flight+gRPC-Protokoll für optimale Leistung. Der folgende Python-Code zeigt ein Beispiel dafür.

from influxdb3 import InfluxDBClient3

client = InfluxDBClient3(
    host="your-cluster-endpoint:8086",
    token="YOUR_TOKEN",
    database="DATABASE_NAME"
)

# SQL query
sql_result = client.query("SELECT * FROM home WHERE room = 'Kitchen'")

# InfluxQL query  
influxql_result = client.query(
    "SELECT MEAN(temp) FROM home WHERE time >= now() - 1h GROUP BY room",
    language="influxql"
)

Vergleichen Sie die SQL- und InfluxQL-Abfragefunktionen

In der folgenden Tabelle werden die SQL- und InfluxQL-Abfragefunktionen verglichen:

Funktion	SQL	InfluxQL
Joins	Unterstützt	Nicht unterstützt
Fensterfunktionen	Vollständige Unterstützung	Begrenzt
Unterabfragen	Unterstützt	Nicht unterstützt
Zeitfunktionen	DATE_BIN, INTERVAL	time()-Gruppierung
Parametrisierte Abfragen	Native Unterstützung	Nicht unterstützt
Lücken füllen	date_bin_gapfill()	fill() Funktion

Wenn Sie diese Abfragefunktionen verstehen und die geeignete Methode für Ihren Anwendungsfall auswählen, können Sie Ihre Zeitreihendaten effizient aus Timestream for InfluxDB 3 abrufen und analysieren.

Vorteile von SQL:

• Umfassende SQL-Implementierung mit Unterstützung für komplexe Abfragen.

• Support für Joins, Unions und Fensterfunktionen.

• Vertraute Syntax für Benutzer mit SQL-Hintergrund.

• Umfangreichere Analysemöglichkeiten.

Vorteile von InfluxQL:

• Speziell für Zeitreihendaten entwickelt.

• Einfachere Syntax für gängige Zeitreihenoperationen.

• Abwärtskompatibilität für Benutzer, die von InfluxDB v1 migrieren.

• Spezialisierte Zeitreihenfunktionen.

Funktionen zur Abfrageoptimierung

InfluxDB 3 bietet mehrere Optimierungsfunktionen zur Verbesserung der Abfrageleistung für bestimmte Anwendungsfälle. Diese Funktionen nutzen In-Memory-Caching und benutzerdefinierte Indexierungsstrategien, um Reaktionszeiten von unter einer Millisekunde für häufig aufgerufene Datenmuster zu ermöglichen.

Letzter Werte-Cache (LVC)

Der Last Value Cache (LVC) speichert die neuesten N Werte für bestimmte Felder im Speicher und ermöglicht so Antwortzeiten von unter 10 ms für Abfragen, die die neuesten Datenpunkte benötigen. Diese Funktion ist sowohl in der Core- als auch in der Enterprise-Edition verfügbar.

Wie funktioniert LVC

Das LVC verwaltet eine speicherinterne Tabelle mit den neuesten Werten für jede eindeutige Kombination von Schlüsselspalten (normalerweise Tags). Zum Beispiel mit Sensordaten:

Table: home
├── Tags: room, wall
└── Fields: temp, humidity, co

LVC Configuration:
- Key columns: room, wall
- Value columns: temp, humidity, co
- Count: 4 (last 4 values)

Der Cache speichert:

Zimmer	Mauer	Zeitarbeiter	Feuchtigkeit	co	variieren
Küche	Osten	22,7	36,5	26	2025-01-26T 20:00:00 Z
Küche	Osten	22,7	36,0	9	2025-01-26T 17:00:00 Z
Küche	Osten	22,7	36,2	3	2025-01-26T 15:00:00 Z
Küche	Osten	22,7	36,1	0	2025-01-26T 10:00:00 Z
Wohnzimmer	nördlich	22,2	36,4	17	2025-01-26T 20:00:00 Z
...	...	...	...	...	...

Erstellen Sie ein LVC

Verwenden Sie den folgenden Befehl, um ein LVC zu erstellen:

influxdb3 create last_cache \
  --database DATABASE_NAME \
  --token YOUR_TOKEN \
  --table home \
  --key-columns room,wall \
  --value-columns temp,hum,co \
  --count 5 \
  --ttl 30mins \
  homeLastCache

Fragen Sie das LVC ab

Verwenden Sie den folgenden Befehl, um eine LVC abzufragen:

-- Query the last cached values
SELECT * FROM last_cache('home', 'homeLastCache')

-- Filter specific series
SELECT * FROM last_cache('home', 'homeLastCache') 
WHERE room = 'Kitchen'

Bewährte Methoden für LVC

• Kardinalität verwalten: Nehmen Sie nur wichtige Tags als Schlüsselspalten auf, um den Speicherverbrauch zu minimieren.

• Anzahl der Werte optimieren: Ausgewogenes Verhältnis zwischen Abfragebedarf und Speicherverbrauch.

• Denken Sie an TTL: Set, das time-to-live für Cache-Einträge geeignet ist.

• Arbeitsspeicher überwachen: Cachegröße = (key_column_cardinality × count × value_columns).

Cache mit eindeutigem Wert (DVC)

Der Distinct Value Cache (DVC) verwaltet eindeutige Werte für bestimmte Spalten im Speicher, wodurch Metadatenabfragen auf Antwortzeiten von unter 30 ms beschleunigt werden. Sowohl in der Core- als auch in der Enterprise-Edition verfügbar.

Wie funktioniert DVC

Der DVC speichert alle eindeutigen Kombinationen von Werten für bestimmte Spalten. Dies ist ideal für Abfragen, bei denen verfügbare Tagwerte oder Metadaten aufgelistet werden müssen.

Beispiel-Cache für Standortdaten:

Land	Bezirk	Stadt
Österreich	Salzburg	Salzburgo
Österreich	Wien	Wien
Belgien	Antwerpen	Antwerpen
Belgien	Westflandern	Brügge
Tschechische Republik	Prag	Prag

Erstellen Sie eine DVD

Verwenden Sie den folgenden Befehl, um einen DVC zu erstellen:

influxdb3 create distinct_cache \
  --database DATABASE_NAME \
  --token YOUR_TOKEN \
  --table wind_data \
  --columns country,county,city \
  --max-cardinality 10000 \
  --max-age 24h \
  windDistinctCache

Fragen Sie den DVC ab

Verwenden Sie den folgenden Befehl, um einen DVC abzufragen:

-- Get all distinct values
SELECT * FROM distinct_cache('wind_data', 'windDistinctCache')

-- Get distinct countries
SELECT DISTINCT country 
FROM distinct_cache('wind_data', 'windDistinctCache')

Best Practices für DVC

• Kardinalitätsgrenzen festlegen: Definieren Sie maximale Kombinationen von Einzelwerten zur Steuerung des Speichers.

• Maximales Alter konfigurieren: Veraltete Werte werden automatisch entfernt.

• Strategische Spalten zwischenspeichern: Konzentrieren Sie sich auf Spalten, die häufig in Metadatenabfragen verwendet werden.

• Cachegröße überwachen: Eine höhere Kardinalität bedeutet, dass mehr Speicher benötigt wird.

Dateiindizes sind nur in Enterprise verfügbar

Nur in der Enterprise Edition verfügbar. Dateiindizes ermöglichen die Anpassung der Art und Weise, wie Daten im Speicher indexiert werden, wodurch die Leistung von Abfragen einzelner Serien erheblich verbessert wird.

Standardmäßige und benutzerdefinierte Indizierung

Standardindizierung: InfluxDB indexiert für alle Tags plus Zeit. 

Benutzerdefinierte Indizierung: Indizieren Sie nur Spalten, die für Ihre Abfragen relevant sind.

Beispiel für Optimierung:

Schema columns: country, state_province, county, city, postal_code
Query patterns: Always filter by country, state_province, city
Custom index: time, country, state_province, city (skip county, postal_code)

Im Folgenden wird gezeigt, wie ein benutzerdefinierter Dateiindex erstellt wird

influxdb3 create file_index \
  --database DATABASE_NAME \
  --token YOUR_TOKEN \
  --table wind_data \
  country,state_province,city

Im Folgenden wird gezeigt, wie ein Dateiindex gelöscht wird:

influxdb3 delete file_index \
  --database DATABASE_NAME \
  --token YOUR_TOKEN \
  --table wind_data

Überlegungen zum Dateiindex

• Komprimierung erforderlich: Indizes werden während der Datenkomprimierung erstellt (Gen2+).

• Nur Zeichenkettenspalten: Kann sowohl Tags als auch Zeichenkettenfelder indizieren.

• Analyse von Abfragemustern: Analysieren Sie Ihre Arbeitslast, bevor Sie benutzerdefinierte Indizes erstellen.

• Optimierung einzelner Serien: Am vorteilhaftesten für Abfragen, die auf bestimmte Serien abzielen.

Verwaltung von Cache-Informationen

Cache-Konfigurationen und Statistiken mithilfe von Systemtabellen anzeigen:

-- View Last Value Caches
SELECT * FROM system.last_caches

-- View Distinct Value Caches  
SELECT * FROM system.distinct_caches

-- Check cache memory usage
SELECT 
  cache_name,
  table_name,
  key_columns,
  value_count,
  memory_size_bytes
FROM system.last_caches

Strategie zur Leistungsoptimierung

Wählen Sie anhand Ihrer Abfragemuster die richtigen Optimierungsfunktionen aus:

Abfragemuster	Empfohlene Funktion	Erwartete Leistung
Aktuelle Werte pro Serie	Cache für den letzten Wert	<10 ms
Verfügbare Tag-Werte	Cache mit eindeutigen Werten	<30 ms
Abfragen für einzelne Serien	Dateiindizes (Unternehmen)	Signifikante Verbesserung
Aggregationen von Zeiträumen	Standardindizes	Basisleistung

Überlegungen zu Speicher und Ressourcen

Formel für den Cache-Speicher:

• LVC: Speicher = Schlüsselkardinalität × Wertanzahl × Wertspalten × Datengröße

• DVC: Speicher = unterschiedliche Kombinationen × Spaltenanzahl × Datengröße

Bewährte Verfahren:

• Beginnen Sie mit kleinen Caches und überwachen Sie die Speichernutzung

• Verwenden Sie TTL-Einstellungen, um das Cache-Wachstum zu begrenzen

• Nur häufig abgefragte Daten zwischenspeichern

• Überwachen Sie die Cache-Trefferraten anhand von Systemtabellen

• Für Unternehmen: Kombinieren Sie Caches mit benutzerdefinierten Dateiindizes, um eine optimale Leistung zu erzielen

Durch die angemessene Nutzung dieser Optimierungsfunktionen können Sie erhebliche Leistungsverbesserungen für bestimmte Abfragemuster erzielen und gleichzeitig den Ressourcenverbrauch effektiv steuern.