Amazon Timestream for LiveAnalytics와 유사한 기능을 원하는 경우 Amazon Timestream for InfluxDB를 고려해 보세요. 간소화된 데이터 수집과 실시간 분석을 위한 10밀리초 미만의 쿼리 응답 시간을 제공합니다. [여기](https://docs.aws.amazon.com//timestream/latest/developerguide/timestream-for-influxdb.html)에서 자세히 알아보세요.
기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Timestream for InfluxDB 3에서 데이터 쿼리
Amazon Timestream for InfluxDB 3는 시계열 데이터를 검색하기 위한 여러 쿼리 API와 프로토콜을 제공합니다. 이 플랫폼은 HTTP 및 Flight(gRPC) 프로토콜을 통해 SQL 및 InfluxQL 쿼리 언어를 모두 지원하여 다양한 사용 사례와 클라이언트 기본 설정에 맞는 유연성을 제공합니다.
## 쿼리 메서드 개요
InfluxDB 3는 다음 쿼리 메서드를 지원합니다.
+ 기본 v3 HTTP API - REST 엔드포인트를 통한 SQL 및 InfluxQL 쿼리
+ influxdb3 CLI - 대화형 쿼리를 위한 명령줄 인터페이스
+ Flight\+gRPC 프로토콜 - 클라이언트 라이브러리를 위한 고성능 바이너리 프로토콜
+ v1 호환성 API - 이전 버전과의 호환성을 위한 레거시 InfluxQL 쿼리
### v3 HTTP 쿼리 API 사용
v3 API는 GET 및 POST 메서드를 모두 지원하는 SQL 및 InfluxQL 쿼리 전용 엔드포인트를 제공합니다.
#### SQL 쿼리(`/api/v3/query_sql`)
GET 요청 예제:
```
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'"
```
POST 요청 예제(복잡한 쿼리의 경우):
```
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 쿼리(`/api/v3/query_influxql`)
InfluxQL 쿼리의 경우 다음을 수행합니다.
```
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"
```
#### 쿼리 파라미터
다음 쿼리 파라미터를 사용할 수 있습니다.
| **파라미터** | **설명** | **필수** |
| --- | --- | --- |
| db | 데이터베이스 이름 | 예 |
| q | 쿼리 문자열(SQL 또는 InfluxQL) | 예 |
| format | 응답 형식(json, jsonl, csv, pretty, parquet) | 아니요(기본값: json) |
| params | 파라미터화된 쿼리의 파라미터 | 아니요 |
#### Influxdb3 CLI 사용
InfluxDB 3 명령줄 인터페이스(CLI)는 `influxdb3` 명령을 사용하여 간접적으로 호출됩니다. 다양한 출력 형식을 지원하며 데이터를 쿼리할 수 있는 대화형 방식을 제공합니다.
다음은 기본 쿼리를 보여줍니다.
```
influxdb3 query \
--host "your-cluster-endpoint:8086" \
--token "YOUR_TOKEN" \
--database "DATABASE_NAME" \
"SELECT * FROM home WHERE time >= now() - INTERVAL '1 day'"
```
다음은 다양한 출력 형식의 쿼리를 보여줍니다.
```
# 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"
```
다음 출력 형식이 지원됩니다.
+ pretty(기본값) - 사람이 읽을 수 있는 테이블 형식
+ json - 표준 JSON 배열
+ jsonl - JSON 행(스트리밍 친화적)
+ csv - 쉼표로 분리된 값입니다.
+ parquet - 이진 열 형식(파일 출력 필요)
### v1 호환성 API 사용
레거시 InfluxQL 쿼리의 경우 `/query` 엔드포인트를 사용합니다.
```
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"
```
## v3 HTTP 쿼리 API에 대한 인증 옵션
+ 전달자 토큰: `Authorization: Bearer TOKEN`
+ 기본 인증: `--user "any:TOKEN"`
+ 쿼리 파라미터: `?p=TOKEN`
## v3 HTTP 쿼리 API의 응답 형식
+ JSON(기본값)
+ CSV(`Accept: application/csv` 헤더 포함)
## SQL 쿼리 예제
다음은 기본 쿼리를 보여줍니다.
```
-- 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
```
다음은 집계 쿼리를 보여줍니다.
```
-- 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
```
다음은 고급 SQL 기능을 보여줍니다.
```
-- 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
```
다음은 InfluxQL 쿼리 예를 보여줍니다.
```
-- 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
```
다음은 시스템 테이블을 쿼리하여 데이터베이스 구조를 이해하고 성능을 모니터링하는 방법을 보여줍니다.
```
-- 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
```
## 쿼리 성능 모범 사례
+ **시간 필터 사용**: 항상 시간 범위 필터를 포함하여 스캔한 데이터를 제한합니다.
+ **인덱스 활용**: 태그 필터를 효과적으로 사용하도록 쿼리를 설계합니다.
+ **적절한 출력 형식을 선택합니다**.
+ 대규모 결과 스트리밍의 경우 jsonl을 사용합니다.
+ 데이터 내보내기 및 분석의 경우 parquet를 사용합니다.
+ 스프레드시트 호환성의 경우 csv를 사용합니다.
+ **집계 최적화**: 시간 기반 그룹화에 DATE\_BIN을 사용합니다.
+ **파라미터화된 쿼리 사용**: 주입 공격을 방지하고 재사용 가능성을 개선합니다.
+ **쿼리 성능 모니터링**: system.queries 테이블에서 느린 쿼리를 확인합니다.
## 클라이언트 라이브러리 쿼리 지원
InfluxDB 3 클라이언트 라이브러리는 최적의 성능을 위해 Flight\+gRPC 프로토콜을 사용합니다. 다음 Python 코드는 이의 예를 보여줍니다.
```
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"
)
```
## SQL 및 InfluxQL 쿼리 기능 비교
다음 표에서는 SQL 쿼리 기능과 InfluxQL 쿼리 기능을 비교합니다.
| **Feature** | **SQL** | **InfluxQL** |
| --- | --- | --- |
| 조인 | 지원됨 | 지원되지 않음 |
| 창 함수 | 전체 지원 | 제한 사항 |
| 하위 쿼리 | 지원됨 | 지원되지 않음 |
| 시간 함수 | DATE\_BIN, INTERVAL | time() 그룹화 |
| 파라미터화된 쿼리 | 기본 지원 | 지원되지 않음 |
| 갭 채우기 | date\_bin\_gapfill() | fill() 함수 |
이러한 쿼리 기능을 이해하고 사용 사례에 적합한 방법을 선택하면 Timestream for InfluxDB 3에서 시계열 데이터를 효율적으로 검색하고 분석할 수 있습니다.
SQL의 장점:
+ 복잡한 쿼리를 지원하는 모든 기능을 갖춘 SQL 구현
+ joins, unions, window 함수 지원
+ SQL 배경 지식을 가진 사용자에게 익숙한 구문
+ 더 광범위한 분석 기능
InfluxQL의 장점:
+ 시계열 데이터용으로 특별히 설계됨
+ 일반적인 시계열 작업을 위한 더 간단한 구문
+ InfluxDB v1에서 마이그레이션하는 사용자를 위한 이전 버전과의 호환성
+ 특수 시계열 함수
## 쿼리 최적화 기능
InfluxDB 3는 특정 사용 사례에 대한 쿼리 성능을 개선하기 위한 몇 가지 최적화 기능을 제공합니다. 이러한 기능은 인 메모리 캐싱 및 사용자 지정 인덱싱 전략을 활용하여 자주 액세스하는 데이터 패턴에 대해 밀리초 미만의 응답 시간을 제공합니다.
### 마지막 값 캐시(LVC)
마지막 값 캐시(LVC)는 지정된 필드에 대한 최신 N 값을 메모리에 저장하여 최신 데이터 포인트가 필요한 쿼리에 대해 10ms 미만의 응답 시간을 활성화합니다. 이 기능은 Core edition과 Enterprise edition 모두에서 사용할 수 있습니다.
#### LVC 작동 방식
LVC는 각 고유한 키 열 조합(일반적으로 태그)에 대한 최신 값의 인 메모리 테이블을 유지합니다. 센서 데이터를 예로 들어 보겠습니다.
```
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)
```
캐시는 다음을 저장합니다.
| **방** | **wall** | **임시** | **습도** | **c**o | **time** |
| --- | --- | --- | --- | --- | --- |
| 주방 | east | 22.7 | 36.5 | 26 | 2025-01-26T20:00:00Z |
| 주방 | east | 22.7 | 36.0 | 9 | 2025-01-26T17:00:00Z |
| 주방 | east | 22.7 | 36.2 | 3 | 2025-01-26T15:00:00Z |
| 주방 | east | 22.7 | 36.1 | 0 | 2025-01-26T10:00:00Z |
| Living Room | north | 22.2 | 36.4 | 17 | 2025-01-26T20:00:00Z |
| ... | ... | ... | ... | ... | ... |
#### LVC 생성
다음 명령을 사용하여 LVC를 생성합니다.
```
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
```
#### LVC 쿼리
다음 명령을 사용하여 LVC를 쿼리합니다.
```
-- Query the last cached values
SELECT * FROM last_cache('home', 'homeLastCache')
-- Filter specific series
SELECT * FROM last_cache('home', 'homeLastCache')
WHERE room = 'Kitchen'
```
#### LVC 모범 사례
+ 카디널리티 관리: 메모리 사용량을 최소화하기 위해 필수 태그만 키 열로 포함합니다.
+ 값 개수 최적화: 쿼리 요구 사항과 메모리 사용량 간의 균형을 유지합니다.
+ TTL 고려: 캐시 항목에 적절한 Time-to-Live를 설정합니다.
+ 모니터 메모리: 캐시 크기 = (key\_column\_cardinality × count × value\_columns)
### 고유 값 캐시(DVC)
고유 값 캐시(DVC)는 메모리의 지정된 열에 대해 고유 값을 유지하여 메타데이터 쿼리를 30ms 미만의 응답 시간으로 가속화합니다. Core edition과 Enterprise edition 모두에서 사용할 수 있습니다.
#### DVC 작동 방식
DVC는 지정된 열에 대한 모든 고유 값 조합을 저장하므로 사용 가능한 태그 값 또는 메타데이터를 나열해야 하는 쿼리에 적합합니다.
위치 데이터에 대한 캐시 예제:
| **국가** | **county** | **도시** |
| --- | --- | --- |
| 오스트리아 | Salzburg | Salzburg |
| 오스트리아 | Vienna | Vienna |
| 벨기에 | Antwerp | Antwerp |
| 벨기에 | West Flanders | Bruges |
| 체코 공화국 | Prague | Prague |
#### DVC 생성
다음 명령을 사용하여 DVC를 생성합니다.
```
influxdb3 create distinct_cache \
--database DATABASE_NAME \
--token YOUR_TOKEN \
--table wind_data \
--columns country,county,city \
--max-cardinality 10000 \
--max-age 24h \
windDistinctCache
```
#### DVC 쿼리
다음 명령을 사용하여 DVC를 쿼리합니다.
```
-- Get all distinct values
SELECT * FROM distinct_cache('wind_data', 'windDistinctCache')
-- Get distinct countries
SELECT DISTINCT country
FROM distinct_cache('wind_data', 'windDistinctCache')
```
#### DVC 모범 사례
+ 카디널리티 한도 설정: 메모리를 제어하기 위한 최대 고유 값 조합을 정의합니다.
+ 최대 기간 구성: 오래된 값을 자동으로 제거합니다.
+ 캐시 전략 열: 메타데이터 쿼리에 자주 사용되는 열에 초점을 맞춥니다.
+ 캐시 크기 모니터링: 카디널리티가 높을수록 더 많은 메모리가 필요합니다.
### Enterprise에서만 사용할 수 있는 파일 인덱스
**Enterprise Edition에서만 사용 가능.** 파일 인덱스를 사용하면 스토리지에서 데이터를 인덱싱하는 방법을 사용자 지정할 수 있으므로 단일 계열 쿼리 성능이 크게 향상됩니다.
#### 기본 인덱싱과 사용자 지정 인덱싱 비교
기본 인덱싱: InfluxDB는 모든 태그와 시간에 대해 인덱싱합니다.
사용자 지정 인덱싱: 쿼리와 관련된 열에 대해서만 인덱싱합니다.
최적화 예제:
```
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)
```
다음은 사용자 지정 파일 인덱스를 생성하는 방법을 보여줍니다.
```
influxdb3 create file_index \
--database DATABASE_NAME \
--token YOUR_TOKEN \
--table wind_data \
country,state_province,city
```
다음은 파일 인덱스를 삭제하는 방법을 보여줍니다.
```
influxdb3 delete file_index \
--database DATABASE_NAME \
--token YOUR_TOKEN \
--table wind_data
```
#### 파일 인덱스 고려 사항
+ 압축 필요: 인덱스는 데이터 압축(gen2\+) 중 빌드됩니다.
+ 문자열 열 전용: 태그와 문자열 필드를 모두 인덱싱할 수 있습니다.
+ 쿼리 패턴 분석: 사용자 지정 인덱스를 생성하기 전에 워크로드를 분석합니다.
+ 단일 계열 최적화: 특정 계열을 대상으로 하는 쿼리에 가장 유용합니다.
### 캐시 정보 관리
시스템 테이블을 사용하여 캐시 구성과 통계를 봅니다.
```
-- 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
```
### 성능 최적화 전략
쿼리 패턴에 따라 적절한 최적화 기능을 선택합니다.
| **쿼리 패턴** | **권장 기능** | **예상 성능** |
| --- | --- | --- |
| 계열당 최신 값 | 마지막 값 캐시 | <10ms |
| 사용 가능한 태그 값 | 고유 값 캐시 | <30ms |
| 단일 계열 쿼리 | 파일 인덱스(Enterprise) | 상당한 개선 |
| 시간 범위 집계 | 표준 인덱스 | 기준 성능 |
### 메모리 및 리소스 고려 사항
**캐시 메모리 공식:**
+ LVC: 메모리 = key\_cardinality × value\_count × value\_columns × data\_size
+ DVC: 메모리 = distinct\_ combinations × column\_count × data\_size
**모범 사례:**
+ 작은 캐시로 시작하고 메모리 사용량 모니터링
+ TTL 설정을 사용하여 캐시 증가 제한
+ 자주 쿼리되는 데이터만 캐시
+ 시스템 테이블을 통해 캐시 적중률 모니터링
+ Enterprise의 경우: 최적의 성능을 위해 캐시를 사용자 지정 파일 인덱스와 결합
이러한 최적화 기능을 적절하게 활용하면 리소스 소비를 효과적으로 관리하면서 특정 쿼리 패턴에 대해 상당한 성능 개선을 달성할 수 있습니다.