쿼리 문자열은 유니코드 문자를 포함합니다. 쿼리 문자열의 최대 길이는 2,000자(영문)입니다. 모든 쿼리 문자열은 최소 하나의 필드 값을 포함합니다. 필드 값은 소문자로 작성하는 것이 좋습니다. 이 경우 Atom, 텍스트, HTML 필드에 대한 검색을 수행할 때 대소문자를 구분하지 않고, 쿼리 문자열에는 대문자 작성으로 인식되는 불리언 연산자 AND, OR, NOT도 포함되기 때문입니다.
쉼표는 distance(home, geopoint(35.2, 40.5)) > 100처럼 함수의 인수를 구분하는 데 사용하거나 따옴표로 둘러싸인 문자열에 포함하여 쿼리 문자열에 사용될 수 있습니다.
쿼리 문자열은 여러 형태를 취할 수 있습니다. 쿼리를 생성하는 주된 방법에는 필드 이름을 포함하거나 포함하지 않는 두 가지가 있습니다. 전체 검색은 필드 값만 포함하는 쿼리 문자열을 사용합니다.
필드 검색은 필드 이름과 필드 값을 지정하는 하나 이상의 표현식이 포함된 쿼리 문자열을 사용합니다.
이 문서에서는 전체 검색과 필드 검색에서 쿼리 문자열을 생성하는 방법과 각각의 경우에 검색 로직이 어떻게 작동하는지에 관하여 설명합니다.
실행된 쿼리 레코드를 보관하려면 애플리케이션에서 쿼리 문자열을 로깅하는 것이 좋습니다.
전체 검색
전체 검색은 모든 문서 필드에 표시될 수 있는 값을 지정하여 문서를 검색하는 기능을 제공합니다. 전체 검색을 수행하려면 하나 이상의 필드 값을 포함한 쿼리 문자열을 작성합니다. 검색 알고리즘이 모든 값의 유형을 인식하여 해당 값을 포함할 수 있는 모든 문서 필드를 검색합니다.
값이 하나인 쿼리
하나의 값을 포함하는 쿼리 문자열을 통한 검색은 다음과 같은 규칙에 따라 처리됩니다.
쿼리 문자열이 한 단어(red) 또는 따옴표로 둘러싸인 문자열("red rose")인 경우, 다음을 포함하는 색인에서 모든 문서를 검색합니다.
- 해당 단어나 따옴표로 둘러싸인 문자열을 포함하는 텍스트 또는 HTML 필드(일치 여부 판단 시 대소문자를 구분하지 않음)
- 해당 단어나 따옴표로 둘러싸인 문자열과 일치하는 값이 있는 atom 필드(일치 여부 판단 시 대소문자를 구분하지 않음)
쿼리 문자열이 숫자('3.14159')인 경우, 다음을 포함하는 모든 문서를 검색합니다.
- 쿼리에 표시되는 숫자와 일치하는 토큰이 포함된 텍스트 또는 HTML 필드('he took 5 minutes'라는 텍스트 필드는 쿼리 '5'와는 일치하지만 '5.0'과는 일치하지 않음)
- 쿼리에 표시되는 숫자와 문자 그대로 일치하는 atom 필드
쿼리 문자열이 yyyy-mm-dd 형식의 날짜인 경우, 다음을 포함하는 모든 문서를 검색합니다.
- 값이 그 날짜와 동일한 날짜 필드(쿼리 문자열의 앞에 오는 0은 선택사항이며, '2012-07-04'와 '2012-7-4'는 동일한 날짜임)
- 쿼리에 표시되는 날짜와 문자 그대로 일치하는 토큰이 포함된 텍스트 또는 HTML 필드
- 쿼리에 표시되는 날짜와 문자 그대로 일치하는 atom 필드
한 단어로 이루어진 쿼리의 앞에 NOT 불리언 연산자(대문자)를 추가할 수 있습니다. 그러면 동일한 규칙에 따라 쿼리 값과 일치하는 필드가 없는 문서의 목록이 생성됩니다. 따라서 쿼리 NOT red는 'red'를 포함하는 모든 텍스트 또는 HTML 필드나 red 값이 있는 모든 Atom 필드를 지니지 않은 모든 문서를 검색합니다.
geopoint 필드에 관해서는 설명하지 않았다는 것을 눈치챘을 것입니다. 지금은 원시 geopoint 값을 문자열로 지정할 수 없으므로 전체 검색에 geopoint가 나타날 수 없습니다.
값이 여러 개인 쿼리
전체 검색 문자열에 여러 개의 값(공백으로 구분)을 지정할 수 있습니다. 단어, 따옴표로 둘러싸인 문자열, 숫자, 날짜 사이의 화이트 스페이스는 암시적 AND 연산자로 취급됩니다. 아래의 두 가지 검색 문자열은 거의 동일하지만 전체 검색이 atom 필드를 취급하는 방식이 다르며, 여기에 대해서는 아래에서 설명합니다.
query = "small red"
query = "small AND red"
여러 개의 값으로 전체 검색을 수행하면 필드 매칭이 문자열의 각 값에서 독립적으로 수행되고 atom 필드 매칭은 특히 다음과 같은 점에서 다르게 처리됩니다.
- 텍스트 또는 HTML 필드에 쿼리 값이 어떤 순서로도 표시될 수 있습니다.
- 여러 필드에 여러 값이 표시될 수 있습니다.
- atom 필드는 쿼리 문자열에 불리언 연산자(
AND,OR,NOT)가 포함되어 있지 않은 경우에만 검색됩니다. 전체 쿼리 문자열이 atom 필드와 일치해야 합니다.
필드를 처리하는 세 번째 규칙에 유의하세요. 'red small'이라는 쿼리 문자열에는 불리언 AND가 포함되어 있지 않으므로(의미가 내포되어 있기는 하지만), 이 경우에는 일치하는 atom 필드를 찾으려고 시도합니다. 'red AND small'이라는 문자열에는 불리언 연산자가 포함되어 있으므로 검색 시 쿼리 문자열을 atom 필드와 일치시키려고 시도하지 않습니다.
다음의 예시는 쿼리 문자열 'rose bud'를 사용하여 검색된 4개의 문서를 보여줍니다. 문서마다 텍스트 필드 2개와 atom 필드 1개가 있습니다. 설명 열은 각 문서가 왜 쿼리를 충족하는지 설명합니다.
| 문서 ID | 텍스트 필드 1 | 텍스트 필드 2 | Atom 필드 | 설명 |
|---|---|---|---|---|
| 1 | mighty like a rose | one bud to bind them all | thorn bush | 일치하는 여러 개의 값이 여러 필드에 나타날 수 있습니다. |
| 2 | wide like a river | like a bud on a rose | tumble weed | 일치하는 여러 개의 값이 끼어드는 텍스트와 함께 동일한 텍스트 또는 HTML 필드에 임의의 순서로 나타날 수 있습니다. |
| 3 | deep like the ocean | the rose bud boys | blue bonnet | 일치하는 여러 개의 값이 동일한 텍스트 또는 HTML 필드에 임의의 순서로 나타날 수 있습니다. |
| 4 | tall like a mountain | the beautiful garden | rose bud | Atom 필드는 해당 값이 전체 쿼리 문자열과 동일하기 때문에 일치합니다. |
쿼리의 값을 반대로 하여 대신에 'bud rose'를 검색할 경우에는 문서 1, 2, 3은 그대로 반환되지만 문서 4는 반환되지 않는다는 점에 유의하세요. atom, 텍스트, HTML 필드에서 정확한 문자의 문자열을 검색하려면 쿼리 문자열에서 해당 문자열을 따옴표로 묶으세요. 이 예시에서 "rose bud"를 검색하면 문서 3과 4만 반환될 것입니다.
부울 연산자
값의 앞에 불리언 연산자 NOT을 사용하고 값과 값 사이에 AND와 OR 연산자를 사용하여 더 복잡한 전체 검색을 지정할 수 있습니다. 이러한 연산자는 대문자로 작성해야 한다는 점에 유의하세요. 이러한 연산자가 따옴표로 묶여진 문자열 안에 나타나면 연산자가 아니라 필드 값의 일부로 취급됩니다. 쿼리 문자열 안에 괄호를 사용하여 로직을 명확하게 할 수 있습니다.
불리언 연산자 우선순위(가장 높은 것에서 가장 낮은 순)는 NOT, OR, AND입니다.
NOT cat AND dogs OR horses --> (NOT cat) AND (dogs OR horses)
NOT cat OR dogs AND horses --> ((NOT cat) OR dogs) AND horses
어간 추출
복수형이나 동사의 어미와 같이 한 단어의 일반적인 변형을 검색하려면 ~ 스템 연산자(물결기호 문자)를 사용합니다. 이 연산자는 공백 없이 값의 앞에 와야 하는 프리픽스 연산자입니다. ~cat이라는 값은 'cat' 또는 'cats'와 일치할 것이고 마찬가지로 ~dog는 'dog' 또는 'dogs'와 일치합니다. 어간 추출 알고리즘에는 실수 방지 처리가 되어 있지 않습니다. ~care라는 값은 'care' 및 'caring'과 일치하지만 'cares' 또는 'cared'와는 일치하지 않습니다. 어간 추출은 텍스트 및 HTML 필드를 검색할 때에만 사용됩니다.
토큰화
문서에 색인이 표시되어 있으면 해당 필드는 토큰화됩니다. 마찬가지로 쿼리 문자열의 값도 토큰화됩니다. 즉, 값이 하나인 쿼리처럼 보이는 것이 실제로는 값이 여러 개인 쿼리로 취급된다는 뜻입니다. 예를 들면 다음과 같습니다.
"real-time" --> "real time"
"2001-12-15" --> "2001 12 15"
"1.5" --> "1 5"
필드 검색
필드 검색은 필드 이름을 통해 특정 문서 필드에 있는 값을 찾습니다. 필드 검색은 필드 이름, 관계 연산자, 필드 값을 지정하는 하나 이상의 표현식으로 구성됩니다. 사용할 수 있는 관계 연산자는 필드의 유형에 따라 결정됩니다. 콜론이나 등호로 표현되는 등호 연산자는 모든 필드 유형에 사용할 수 있습니다. 여러 가지 유형의 필드에 적용되는 필드 쿼리 문자열의 예를 들면 다음과 같습니다.
query = "pet = dog"
query = "author = \"Ray Bradbury\""
query = "color:red"
query = "NOT color:red"
query = "price < 500"
query = "birthday>=2011-05-10"
관계 연산자 양쪽의 공백은 선택 사항입니다. 전체 검색 쿼리 문자열과 마찬가지로 텍스트, HTML, atom 필드의 값을 따옴표로 묶어서 특정 문자열을 지정할 수 있으며 대문자 NOT을 앞에 붙여서 필드 값의 표현식을 무효화할 수 있습니다.
atom 필드의 쿼리
atom 필드의 값은 문자열입니다. atom 필드의 쿼리는 대소문자를 구분하지 않습니다. 쿼리가 공백 또는 마침표로 필드 값을 지정하는 경우, 해당 값을 쿼리 문자열 안에 따옴표로 묶으세요. atom 필드에서 유일하게 유효한 관계 연산자는 등호 연산자입니다. atom 필드의 전체 콘텐츠는 쿼리 값과 일치해야 하는데, 여기에는 필드에 문자나 악센트 부호 문자를 결합한 모든 유니코드가 포함됩니다. atom 필드에서는 어간 추출이 지원되지 않습니다.
| 쿼리 문자열 | 설명 |
|---|---|
"weather=stormy"
|
등호 연산자의 모든 형식이 유효합니다. 'stormy'와 일치하는 weather 필드가 있는 문서를 검색합니다. |
"Title: \"Tom&Jerry\""
|
공백 또는 특수문자가 포함된 atom 필드를 검색할 경우, 해당 값을 따옴표로 묶습니다. |
"Color = (red OR blue)"
|
괄호와 논리 연산자 OR을 사용하여 대체 필드 값 목록을 지정할 수 있습니다. |
텍스트 및 HTML 필드의 쿼리
텍스트 및 HTML 필드에서 유일하게 유효한 관계 연산자는 등호 연산자입니다. 이 경우, 연산자란 '필드가 값과 같다'는 뜻이 아니라 '필드에 값이 포함되어 있다'는 뜻입니다. 어간 추출 연산자를 사용하여 단어의 변형을 검색할 수 있습니다. 또한 OR 및 AND 연산자를 사용하여 필드 값에 복잡한 불리언 표현식을 지정할 수도 있습니다. 따옴표로 묶인 문자열 안에 불리언 연산자가 나타날 경우 이 연산자는 특별히 취급되지 않으며, 일치시킬 문자 문자열의 또 다른 일부일 뿐입니다. HTML 필드를 검색할 때 HTML 마크업 태그 안의 텍스트는 무시된다는 점을 기억하세요. 텍스트 및 HTML 필드의 쿼리는 대소문자를 구분하지 않습니다. 이러한 필드에 색인이 표시되어 있는 경우, 해당 필드에 있는 문자와 악센트 부호 문자가 결합된 모든 유니코드가 악센트가 적용되지 않은 문자로 '정규화'됩니다. 문자와 악센트의 결합은 이러한 필드의 쿼리 문자열에서도 정규화됩니다. 따라서 쿼리에 악센트가 적용된 형태가 포함될 수도 있고 그렇지 않을 수도 있으나 두 경우 모두 필드와 일치할 것입니다.
| 쿼리 문자열 | 설명 |
|---|---|
"Comment = great" |
등호 연산자의 모든 형식이 유효합니다. Comment 필드에 'great'라는 단어가 최소 한 번 등장하는 comment 필드가 있는 문서를 검색합니다. |
"Comment = (great big ball)"
|
필드에서 두 개 이상의 단어(순서에 관계없이)를 검색하려면 해당 단어를 괄호로 묶습니다. 이 쿼리 문자열은 순서에 관계없이 세 개 단어 모두가 포함된(그 사이에 다른 단어가 임의의 수만큼 포함되어 있음) Comment 필드가 있는 문서를 검색합니다. 단어 사이의 공백은 논리 AND를 의미하는데, 두 번째 형태가 이를 명확히 보여줍니다. |
"Comment = \"insanely great\""
|
특정 텍스트 문자열을 검색하려면 해당 문자열을 따옴표로 묶습니다. 이 쿼리는 'insanely great'(그리고 동일한 것으로 토큰화된 'insanely-great')라는 어구를 포함하는 Comment 필드가 있는 문서를 검색합니다. |
"pet = ~dog"
|
어간 추출 연산자는 pet 필드의 'dog'라는 단어의 변형과 일치합니다. |
"Color = (red OR blue)" |
대안 목록에서 일치 항목을 검색하려면, 목록을 괄호로 묶되 대안 사이에 키워드 OR을 포함합니다. 이 쿼리는 Color 필드에 'red' 또는 'blue'가 포함되었거나 아니면 둘 다 포함된 문서를 검색합니다. |
"weather = ((rain OR snow) AND cold)" |
괄호와 함께 논리 연산자 OR과 AND를 사용하여 더 복잡한 필드 값을 지정할 수 있습니다. |
"weather = \"rain OR shine\"" |
논리 연산자 OR은 따옴표로 묶인 문자열에 삽입되어 있으므로 관계 연산자로 취급되지 않습니다. 이 쿼리 문자열은 'rain or shine'이라는 문자열이 포함된 weather 필드가 있는 문서를 검색합니다. |
숫자 필드의 쿼리
숫자 필드 값은 정수, 십진수, 지수로 작성될 수 있습니다.
숫자 필드에 유효한 관계 연산자는 등호 연산자가 있는 미만 또는 초과 연산자(<, <=, >, >=)입니다. 부등(!=) 연산자는 없다는 점에 유의하세요. 숫자 필드의 쿼리 문자열의 예를 들면 다음과 같습니다.
"quantity = 10000"
"size: 4"
"price < 9.99"
"theta > 1.5E-2"
날짜 필드의 쿼리
날짜 필드 값은 yyyy-mm-dd form의 형식을 취해야 합니다. 한 자리 숫자로 된 달과 날의 경우 앞의 0은 선택 사항입니다. 날짜 필드에 유효한 관계 연산자는 등호 연산자가 있는 미만 또는 초과 연산자(<, <=, >, >=)입니다. 부등 연산자는 없다는 점에 유의하세요. 표현식 앞에 NOT 연산자를 추가하여 무효화할 수 있습니다. 다음은 날짜 필드에 대한 쿼리 문자열의 예시입니다.
"start_date: 2012-05-20"
"end_date: 2013-5-1"
"birthday >= 2000-12-31"
"NOT birthday = 2000-12-25"
지리 좌표 필드의 쿼리
지리 좌표 필드에서 작동하는 관계 연산자는 없으므로 쿼리 문자열에서 직접 지리 좌표 필드의 이름을 지정할 수 없습니다. Search API에서는 지리 좌표 필드가 포함된 쿼리에 사용할 수 있는 두 가지 특수 함수를 제공합니다.
geopoint(lat,long)- 위도와 경도가 있는 지리 좌표를 정의합니다.
distance(point1, point2)- 두 지리 좌표 간의 거리를 미터 단위로 계산합니다. 지리 좌표 필드의 이름이나 지리 좌표 함수의 호출을 사용하여 각 지점을 지정할 수 있습니다. 필드 이름 2개를 이 함수의 인수로 제시할 수 없다는 점에 유의하세요. 적어도 인수 1개는 상수여야 합니다.
이러한 함수는 특정 상수 위치와 관련한 위치를 검색하는 쿼리를 생성하는 데 사용할 수 있습니다. 다음의 예에서는 색인에 'survey_marker'와 'home'이라는 이름의 지리 좌표 필드가 있는 문서가 포함되어 있다고 가정합니다.
| 쿼리 문자열 | 설명 |
|---|---|
"distance(survey_marker, geopoint(35.2, 40.5)) < 100" |
주어진 지리 좌표에서 100미터 미만인 마커를 검색합니다. |
"distance(home, geopoint(35.2, 40.5)) > 100" |
주어진 지리 좌표에서 100미터를 초과하는 집을 검색합니다. |
위치정보를 사용하는 애플리케이션은 일반적으로 브라우저에서 정보를 수신합니다. 사용자가 허용하는 경우, 사용자의 IP 주소를 통해 위치를 추정하거나 사용자가 우편번호를 입력할 수 있습니다. Google Maps Geolocation API와 같은 다른 API에서도 위치를 가져올 수 있습니다.
여러 필드의 쿼리
여러 개의 필드 쿼리 표현식을 공백으로 구분하여 순서대로 나열함으로써 하나의 쿼리에 결합할 수 있습니다. 이렇게 하면 각 표현식 사이에 AND가 묵시적으로 배치되므로 모든 표현식이 충족되어야만 문서를 검색할 수 있습니다. 표현식 사이에 명시적으로 AND와 OR 연산자를 추가할 수 있으며 괄호를 사용하여 로직을 명확하게 할 수 있습니다.
| 쿼리 문자열 | 설명 |
|---|---|
"product=piano manufacturer=steinway""product=piano AND manufacturer=steinway"
|
이 문자열은 Steinway 피아노를 모두 검색합니다. 용어 사이의 공백은 논리 AND를 의미하는데, 두 번째 형태가 이를 명확히 보여줍니다. |
"product=piano AND NOT manufacturer=steinway"
|
Steinway 피아노가 아닌 모든 피아노를 검색합니다. |
"product=piano AND price<2000" |
이 쿼리는 저렴한 피아노를 검색합니다. |
전체 검색과 필드 검색의 혼합
쿼리 문자열은 전체 검색 표현식과 필드 검색 표현식을 개수에 관계없이 포함할 수 있습니다. 표현식 사이의 공백은 AND로 취급됩니다. OR 및 AND를 괄호와 함께 명시적으로 사용할 수도 있습니다. 표현식은 해당 유형의 용어와 연결된 규칙에 따라 처리됩니다.
| 쿼리 문자열 | 설명 |
|---|---|
"keyboard great price<5000"
|
텍스트, HTML, atom 필드에 'great'과 'keyboard'라는 단어가 등장하고 5,000 미만의 price 필드가 있는 문서를 검색합니다.
AND가 묵시적으로 적용되는데, 두 번째 형태가 여기에 해당됩니다.
|
"keyboard OR product=piano" |
piano를 포함하는 product 필드가 있는 문서 또는 keyboard가 포함된 텍스트, HTML, atom 필드가 있는 문서를 검색합니다. |