SQL 및 PPL 질의 응답 형식
SQL 및 PPL 질의 응답 형식 (SQL and PPL query response formats)
OpenSearch는 SQL과 PPL 질의에 대해 jdbc, csv, raw, json 네 가지 응답 형식을 제공하며, 각각 용도가 달라요. jdbc 형식은 스키마 정보를 제공하고 페이지네이션 같은 추가 기능이 있어 널리 사용돼요. JDBC 드라이버 외에도 다양한 클라이언트가 상세하고 잘 형식화된 응답을 활용할 수 있답니다.
출처: 문서
본문
JDBC 형식
기본적으로 SQL 플러그인은 표준 JDBC 형식으로 응답을 반환해요. 이 형식은 스키마와 결과 집합을 모두 잘 형식화해야 하는 JDBC 드라이버와 클라이언트를 위해 제공돼요.
예시 요청
다음 질의는 응답 형식을 지정하지 않으므로 형식이 jdbc로 설정돼요.
POST _plugins/_sql
{
"query" : "SELECT firstname, lastname, age FROM accounts ORDER BY age LIMIT 2"
}
예시 응답
응답에서 schema는 필드 이름과 타입을 담고, datarows 필드는 질의 결과를 담고 있어요.
{
"schema": [{
"name": "firstname",
"type": "text"
},
{
"name": "lastname",
"type": "text"
},
{
"name": "age",
"type": "long"
}
],
"total": 4,
"datarows": [
[
"Nanette",
"Bates",
28
],
[
"Amber",
"Duke",
32
]
],
"size": 2,
"status": 200
}
어떤 종류의 오류든 발생하면 OpenSearch는 오류 메시지를 반환해요.
다음 질의는 존재하지 않는 필드 unknown을 검색해요.
POST /_plugins/_sql
{
"query" : "SELECT unknown FROM accounts"
}
응답에는 오류 메시지와 오류 원인이 포함돼요.
{
"error": {
"reason": "Invalid SQL query",
"details": "Field [unknown] cannot be found or used here.",
"type": "SemanticAnalysisException"
},
"status": 400
}
OpenSearch DSL JSON 형식
형식을 json으로 설정하면 OpenSearch의 원래 응답이 JSON 형식으로 반환돼요. 이는 OpenSearch의 네이티브 응답이기 때문에 이를 파싱하고 해석하는 데 추가적인 노력이 필요해요.
예시 요청
다음 질의는 응답 형식을 json으로 설정해요.
POST _plugins/_sql?format=json
{
"query" : "SELECT firstname, lastname, age FROM accounts ORDER BY age LIMIT 2"
}
예시 응답
응답은 OpenSearch의 원래 응답이에요.
{
"_shards": {
"total": 5,
"failed": 0,
"successful": 5,
"skipped": 0
},
"hits": {
"hits": [{
"_index": "accounts",
"_type": "account",
"_source": {
"firstname": "Nanette",
"age": 28,
"lastname": "Bates"
},
"_id": "13",
"sort": [
28
],
"_score": null
},
{
"_index": "accounts",
"_type": "account",
"_source": {
"firstname": "Amber",
"age": 32,
"lastname": "Duke"
},
"_id": "1",
"sort": [
32
],
"_score": null
}
],
"total": {
"value": 4,
"relation": "eq"
},
"max_score": null
},
"took": 100,
"timed_out": false
}
CSV 형식
결과를 CSV 형식으로 반환하도록 지정할 수도 있어요.
예시 요청
POST /_plugins/_sql?format=csv
{
"query" : "SELECT firstname, lastname, age FROM accounts ORDER BY age"
}
예시 응답
firstname,lastname,age
Nanette,Bates,28
Amber,Duke,32
Dale,Adams,33
Hattie,Bond,36
CSV 형식에서 결과 살균(sanitize)하기
기본적으로 OpenSearch는 다음 규칙에 따라 헤더 셀(필드 이름)과 데이터 셀(필드 내용)을 살균해요.
- 셀이
+,-,=또는@로 시작하면, 살균기가 셀 시작 부분에 작은따옴표(')를 삽입해요. - 셀에 쉼표(
,)가 하나 이상 포함되면, 살균기가 셀을 큰따옴표(")로 감싸요.
예시
다음 질의는 특수 문자로 시작하거나 쉼표를 포함하는 셀을 가진 문서를 인덱싱해요.
PUT /userdata/_doc/1?refresh=true
{
"+firstname": "-Hattie",
"=lastname": "@Bond",
"address": "671 Bristol Street, Dente, TN"
}
다음 질의로 CSV 형식의 결과를 요청할 수 있어요.
POST /_plugins/_sql?format=csv
{
"query" : "SELECT * FROM userdata"
}
응답에서 특수 문자로 시작하는 셀에는 '가 접두사로 붙어요. 쉼표가 있는 셀은 따옴표로 둘러싸여요.
'+firstname,'=lastname,address
'Hattie,'@Bond,"671 Bristol Street, Dente, TN"
살균을 건너뛰려면 sanitize 질의 파라미터를 false로 설정하세요.
POST /_plugins/_sql?format=csvandsanitize=false
{
"query" : "SELECT * FROM userdata"
}
응답에는 원래 CSV 형식의 결과가 포함돼요.
=lastname,address,+firstname
@Bond,"671 Bristol Street, Dente, TN",-Hattie
Raw 형식
raw 형식을 사용하면 결과를 후처리를 위해 다른 명령줄 도구로 파이프 할 수 있어요.
예시 요청
POST /_plugins/_sql?format=raw
{
"query" : "SELECT firstname, lastname, age FROM accounts ORDER BY age"
}
예시 응답
Nanette|Bates|28
Amber|Duke|32
Dale|Adams|33
Hattie|Bond|36
기본적으로 OpenSearch는 다음 규칙에 따라 raw 형식의 결과를 살균해요.
- 데이터 셀에 파이프 문자(
|)가 하나 이상 포함되면, 살균기가 셀을 큰따옴표로 감싸요.
예시
다음 질의는 필드에 파이프 문자(|)가 있는 문서를 인덱싱해요.
PUT /userdata/_doc/1?refresh=true
{
"+firstname": "|Hattie",
"=lastname": "Bond|",
"|address": "671 Bristol Street| Dente| TN"
}
다음 질의로 raw 형식의 결과를 요청할 수 있어요.
POST /_plugins/_sql?format=raw
{
"query" : "SELECT * FROM userdata"
}
질의는 | 문자가 큰따옴표로 둘러싸인 셀을 반환해요.
"|address"|=lastname|+firstname
"671 Bristol Street| Dente| TN"|"Bond|"|"|Hattie"