조회 매개변수
쿼리 매개변수는 IBM Cloudant 쿼리 요청의 출력을 변경하여 정렬 순서, 반환되는 필드 또는 응답 페이지 매김을 변경합니다. 매개변수는 selector 필드와 함께 쿼리에 제공됩니다.
매개변수 개요
이 JSON 문서는 사용 가능한 모든 쿼리 매개변수를 사용합니다:
{
// Query selector
"selector": {
"year": {
"$gt": 2010
}
},
// Specify fields to return
"fields": ["_id", "_rev", "year", "title"],
// Specify sort order
"sort": [{"year": "asc"}],
// Return a maximum number of results
"limit": 10,
// Start returning results from a previous bookmark (pagination)
"bookmark":"g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJB"
// Hint to use a specific index for a query
"use_index": "_design/32372935e14bed00cc6db4fc9efca0f1537d34a8",
// Disallow using a different index than the specified index
"allow_fallback": false
}
반환할 필드 지정
데이터베이스에서 선택할 때 문서에 대해 어떤 필드가 반환되는지 지정할 수 있습니다. 이는 이점을 제공할 수 있습니다:
- 결과를 애플리케이션에 필요한 문서 파트만으로 제한합니다.
- 응답의 크기가 감소합니다.
반환할 필드는 쿼리에서 fields 배열을 사용하여 지정합니다. 제공된 필드 이름은 점선 표기법을 사용하여 서브필드에 액세스할 수 있습니다.
이 쿼리는 결과 문서에서 지정된 4개의 필드만 반환합니다:
{
"selector": {
"Actor_name": "Robert De Niro"
},
"fields": [
"Actor_name",
"Movie_year",
"_id",
"_rev"
]
}
지정된 필터 필드만 응답에 포함됩니다. _id 또는 기타 메타데이터 필드는 자동으로 포함되지 않습니다.
정렬 결과
쿼리에서 sort 필드를 사용하여 반환된 결과의 정렬 방식을 지정합니다.
sort 필드에는 필드 이름과 방향 쌍의 목록이 배열로 표현됩니다, 배열로 표현됩니다. 첫 번째 필드 이름 및 방향 쌍은 최상위 레벨의 정렬입니다. 추가 쌍이 제공되면 다음 정렬 수준을 지정합니다.
정렬 필드는 임의의 필드가 될 수 있습니다. 서브필드에 필요한 경우 점선 표기법을 사용하십시오.
방향 값은 오름차순의 경우 asc, 내림차순의 경우 desc 입니다:
"sort": [{ "fieldName1": "desc" }, { "fieldName2": "desc" }]
방향 값을 제외하는 경우 기본값인 asc가 사용됩니다. 오름차순 정렬의 경우 다음과 같은 단축키를 사용할 수 있습니다:
"sort": [ "fieldName1", "fieldName2" ]
일반적인 요구사항은 선택기를 사용하여 일부 컨텐츠를 검색한 후 지정된 필드에 따라 선호하는 방향으로 결과를 정렬하는 것입니다.
정렬을 사용하려면 정렬 필드가 포함된 인덱스를 정의해야 합니다.
json 인덱스를 사용하는 경우 필드는 정렬과 동일한 순서로 지정해야 합니다.
현재는 IBM Cloudant 조회에서 정렬 순서가 다른 복수의 필드를 지원하지 않기 때문에 방향은 모두 오름차순이거나 모두 내림차순이어야 합니다.
방향이 오름차순인 경우 오브젝트 대신 문자열을 사용하여 정렬 필드를 지정할 수 있습니다.
텍스트 인덱스를 사용한 정렬
text 인덱스에 대한 정렬 쿼리에서 정렬되는 필드의 유형을 확인할 수 없는 필드 이름의 경우, 필드 유형을 지정해야 할 수 있습니다. 예를 들어, 다음과 같습니다.
"sort": [ { "<fieldname>:string": "asc" } ]
| 조회에서 사용되는 인덱스는 무엇입니까? | 필드 유형 요구사항 |
|---|---|
| JSON 인덱스 | 없음 |
| 모든 문서에 있는 모든 필드의 텍스트 인덱스 | 데이터베이스에 정렬 필드의 유형이 한 가지인 문서가 포함되어 있는 경우 조회에서 정렬 필드를 지정하십시오. 또한 정렬 필드의 유형이 다른 문서가 포함되어 있는 경우에도 조회에서 정렬 필드를 지정하십시오. |
| 다른 모든 텍스트 인덱스 | 조회에 있는 모든 정렬 필드의 유형을 지정하십시오. |
구문을 사용할 때 모든 문서의 모든 필드의 텍스트 인덱스가 작성됩니다.
"index": {}.
필드에 서로 다른 데이터 유형이 포함된 경우 정렬 순서가 정의되지 않습니다. 이 특성은 텍스트와 보기 인덱스 간의 중요한 차이점입니다. 서로 다른 데이터 유형의 필드에 대한 정렬 동작은 이후 버전에서 변경될 수 있습니다.
페이지 매김
IBM Cloudant 조회에서는 책갈피 필드를 통한 페이지 매김이 지원됩니다. 모든 _find 응답에는 IBM Cloudant에서 나중에 조회 시 재개할 위치를 판별하기 위해 사용하는 책갈피 - 토큰이 포함되어 있습니다. 다음 조회 결과 세트를 가져오려면 다음 요청에 이전 응답에서 수신된 책갈피를 추가하십시오. 선택기는 동일하게 유지해야 합니다. 그렇지 않을 경우 예기치 않은 결과가 수신됩니다. 역방향으로
페이지를 매기려는 경우 이전 책갈피를 사용하여 이전 결과 세트를 리턴할 수 있습니다.
책갈피의 존재가 더 많은 결과를 보장하지는 않습니다. 요청된 페이지 크기에서 리턴되는 결과 수와 비교하여 결과 세트의 끝 부분에 도달했는지 여부를 테스트할 수 있습니다. 리턴되는 결과가 한계보다 적은 경우 결과 세트에서 더 이상 결과가 리턴되지 않습니다.
특정 인덱스의 힌트 사용
조회에서 특정 인덱스를 사용하도록 지시하려면 조회에 use_index 매개변수를 추가하십시오. 이는 힌트이며, 해당 인덱스를 쿼리에 사용할 수 없는 경우 대체 인덱스가 사용됩니다.
use_index 매개변수의 값에서는 다음 형식 중 하나를 사용합니다.
"use_index": "$DDOC""use_index": ["$DDOC","$INDEX_NAME"]
이 예제 쿼리는 use_index 로 특정 인덱스를 힌트하는 것을 보여줍니다:
{
"selector": {
"$text": "Pacino",
"year": 2010
},
"use_index": "_design/32372935e14bed00cc6db4fc9efca0f1537d34a8"
}
특정 인덱스 강제 사용
allow_fallback 매개변수를 use_index 과 결합하여 특정 인덱스를 강제로 사용하도록 합니다. 쿼리에 인덱스를 사용할 수 없는 경우 쿼리는 오류 응답을 반환합니다.
use_index 을 지정하지 않고 "allow_fallback": false 을 사용하면 _all_docs 기본 제공 인덱스를 사용할 수 없습니다.
이 예제 쿼리는 use_index 과 함께 allow_fallback 을 사용하여 특정 인덱스를 강제 적용하는 것을 보여줍니다:
{
"selector": {
"$text": "Pacino",
"year": 2010
},
"use_index": "_design/32372935e14bed00cc6db4fc9efca0f1537d34a8",
"allow_fallback": false
}