참고: Java 8은 2024년 1월 31일 지원 종료되었습니다. 기존 Java 8 애플리케이션은 계속 실행되고 트래픽을 수신합니다. 그러나 지원 종료 날짜 이후에는 해당 런타임을 사용하는 애플리케이션의 재배포를 App Engine에서 차단할 수 있습니다. 지원되는 최신 Java 버전으로 마이그레이션하는 것이 좋습니다.

쿼리 및 정렬 옵션

쿼리 문자열만 사용하여 search() 메서드를 호출하면 다음과 같은 기본 쿼리 옵션에 따라 결과가 반환됩니다.

문서가 내림차순으로 정렬되어 반환됨
문서가 한 번에 20개씩 그룹으로 반환됨
검색된 문서에 원본 필드가 모두 포함됨

Query 클래스의 인스턴스를 search()에 대한 인수로 사용하여 이러한 옵션을 변경할 수 있습니다.

Query 클래스를 사용하면 한 번에 반환할 문서 개수를 지정할 수 있습니다. 검색된 문서의 콘텐츠를 맞춤설정할 수도 있습니다. 문서 식별자만 요청하거나 문서에 필드 하위 집합만 포함되도록 요청할 수 있습니다. 또한 검색된 문서에서 커스텀 필드를 만들 수도 있습니다. 예를 들면 스니펫(일치하는 문자열 주변의 텍스트를 보여주는 텍스트 필드의 조각), 필드 표현식(문서의 다른 필드에서 파생된 값이 있는 필드)이 있습니다.

쿼리 옵션과 별도로 Query 클래스에는 SortOptions 클래스의 인스턴스도 포함할 수 있습니다. 정렬 옵션을 사용하여 정렬 순서를 변경하고 여러 키를 기준으로 결과를 정렬할 수 있습니다.

Query 클래스를 사용하여 검색

Query 클래스의 인스턴스를 사용하여 검색할 때는 클래스의 인스턴스를 여러 단계로 구성해야 합니다. 일반적인 순서는 다음과 같습니다.

쿼리 문자열을 만듭니다.
필요한 경우 SortOptions를 만듭니다.
QueryOptions를 만듭니다.
쿼리 문자열과 QueryOptions(선택사항)를 포함하는 Query 객체를 만듭니다.
Query 객체에서 검색 메서드를 호출합니다.

다음 예시와 같이 QueryOptions.Builder 및 SortOptions.Builder 클래스의 인스턴스에서 setter 메서드를 호출하여 다양한 쿼리 및 정렬 옵션을 지정합니다.

try {
  // Build the SortOptions with 2 sort keys
  SortOptions sortOptions =
      SortOptions.newBuilder()
          .addSortExpression(
              SortExpression.newBuilder()
                  .setExpression("price")
                  .setDirection(SortExpression.SortDirection.DESCENDING)
                  .setDefaultValueNumeric(0))
          .addSortExpression(
              SortExpression.newBuilder()
                  .setExpression("brand")
                  .setDirection(SortExpression.SortDirection.DESCENDING)
                  .setDefaultValue(""))
          .setLimit(1000)
          .build();

  // Build the QueryOptions
  QueryOptions options =
      QueryOptions.newBuilder()
          .setLimit(25)
          .setFieldsToReturn("model", "price", "description")
          .setSortOptions(sortOptions)
          .build();

  // A query string
  String queryString = "product: coffee roaster AND price < 500";

  //  Build the Query and run the search
  Query query = Query.newBuilder().setOptions(options).build(queryString);
  IndexSpec indexSpec = IndexSpec.newBuilder().setName(indexName).build();
  Index index = SearchServiceFactory.getSearchService().getIndex(indexSpec);
  Results<ScoredDocument> result = index.search(query);
  return result;
} catch (SearchException e) {
  // handle exception...
}

QueryOptions

QueryOptions.Builder를 사용하여 쿼리 옵션을 설정해야 합니다. 이 속성에 직접 액세스할 권한은 없습니다.

다음 속성은 반환되는 결과의 개수와 순서를 제어합니다. 함께 사용할 수 없는 오프셋 및 커서 옵션은 페이지로 나누기를 지원합니다. 이들 옵션은 선택된 문서 중에서 결과에 반환될 문서를 지정합니다.

속성	설명	기본값	최대
`Limit`	결과에 반환할 최대 문서 수입니다.	20	1000
`NumberFoundAccuracy`	이 속성은 `Results.getNumberFound()`에 의해 반환되는 결과의 정확도를 결정합니다. 실제로 계산되는 일치 개수에 대한 제한을 설정하여, 제한에 도달하면 검색을 중지합니다. 인덱스의 일치 항목 수가 제한보다 작거나 같으면 반환되는 개수가 정확합니다. 그렇지 않으면 반환된 개수는 발견된 일치 항목과 색인의 크기 및 구조를 기반으로 한 추정치입니다. 이 속성에 높은 값을 설정하면 검색 작업의 복잡성에 영향을 미치고 시간 초과가 발생할 수 있습니다.	지정되지 않은 경우 정확도가 `Limit`와 동일한 값으로 설정됩니다.	25000
`Offset`	반환할 결과에서 첫 번째 문서의 오프셋입니다.	0. 일치하는 모든 문서가 결과에 포함됩니다(제한값까지).	1,000
`Cursor`	오프셋 대신 커서를 사용하여 문서 그룹을 정렬된 순서로 검색할 수 있습니다. 커서가 연속 쿼리에 전달되거나 연속 쿼리에서 나올 때 업데이트되기 때문에, 이전 검색의 끝에서 각각 새로운 검색을 계속할 수 있습니다. 커서 및 오프셋은 결과 처리 페이지에 설명되어 있습니다.	Null. 일치하는 모든 문서가 결과에 포함됩니다(제한값까지).	-
`SortOptions`	`SortOptions` 객체를 설정하여 검색 결과의 순서를 제어합니다. `SortOptions`의 인스턴스에는 아래에 설명되어 있는 고유한 속성 집합이 있습니다.	Null. 문서를 내림차순으로 정렬합니다.	-

다음 속성은 결과에 나타나는 문서 필드를 제어합니다.

속성	설명	기본값
`ReturningIdsOnly`	`True` 또는 `False`로 설정합니다. `True`면 결과에 반환되는 문서에 ID만 포함되고 필드는 포함되지 않습니다.	`False`(모든 필드 반환)
`FieldsToReturn`	결과에 포함할 문서 필드를 지정합니다. 100개 이하의 필드를 지정할 수 있습니다.	모든 문서 필드를 반환합니다(최대 100개).
`ExpressionsToReturn`	검색 결과에 반환되는 각 문서에 추가되는 계산 필드를 설명하는 필드 표현식입니다. 이 필드는 문서의 표현식 속성에 추가됩니다. 필드 값은 하나 이상의 문서 필드를 포함할 수 있는 표현식을 작성하여 지정합니다.	없음
`FieldsToSnippet`	텍스트 필드 이름의 목록입니다. 스니펫은 필드마다 생성됩니다. 검색 결과에서 문서의 표현식 속성에 추가되는 계산된 필드입니다. 스니펫 필드는 소스 필드와 이름이 같습니다. 이 옵션은 검색이 결과 `snippet("query-string", field-name)`을 검색하는 데 사용한 것과 동일한 쿼리 문자열을 기반으로 일치하는 문자열이 최대 한 개인 스니펫을 생성하면서 두 개의 인수만 포함하는 스니펫 함수를 암시적으로 사용합니다. 스니펫 함수를 명시적으로 호출하는 필드 표현식을 추가하여 `ExpressionsToReturn` 옵션을 사용하면 맞춤 스니펫도 만들 수 있습니다.	없음

SortOptions

SortOptions 속성은 검색 결과의 순서와 점수를 제어합니다. SortOptions.Builder를 사용하여 정렬 옵션을 설정해야 합니다. 이 속성에 직접 액세스할 권한은 없습니다.

SortOptions 속성은 검색 결과의 순서와 점수를 제어합니다.

속성	설명	기본값
`SortExpressions`	문서의 다차원 정렬을 나타내는 `SortExpressions` 목록입니다.	없음
`MatchScorer`	선택적 `MatchScorer` 객체입니다. 이 속성이 있으면 검색어 빈도에 따라 문서에 점수가 매겨집니다. 점수는 `_score` 필드로 제공됩니다. 문서에 점수를 매기는 경우 청구 가능한 작업과 실행 시간 면에서 모두 많은 비용이 들 수 있으며 검색 속도가 느려질 수 있습니다. 점수 매기기는 되도록 사용하지 않는 것이 좋습니다.	없음
`Limit`	점수를 매기거나 정렬할 객체의 최대 개수입니다. 10,000개를 초과할 수 없습니다.	1,000

여러 키를 기준으로 정렬

여러 개의 정렬 키를 기준으로 검색 결과의 순서를 지정할 수 있습니다. 각 키는 단순한 필드 이름일 수도 있고 여러 필드에서 계산된 값일 수도 있습니다. 정렬 옵션과 관련하여 '표현식'이라는 용어는 여러 가지 의미로 사용됩니다. SortOption 자체에 표현식 속성이 있습니다. 이 속성은 정렬 키에 해당하는 SortExpression 객체의 목록입니다. 마지막으로 각 SortExpression 객체에는 정렬 키 값을 계산하는 방식을 지정하는 표현식 속성이 있습니다. 이 표현식은 다음 섹션의 규칙에 따라 작성됩니다.

SortExpression은 정렬 방향과 문서의 표현식을 계산할 수 없는 경우 사용할 기본 키 값도 정의합니다. 다음은 전체 속성 목록입니다.

속성	설명	기본값
`Expression`	일치하는 각 문서의 결과를 정렬할 때 평가할 표현식입니다.	없음
`Direction`	검색 결과를 정렬할 방향으로, `ASCENDING` 또는 `DESCENDING`입니다.	`DESCENDING`
`DefaultValue` `DefaultValueDate` `DefaultValueNumber`	문서에 필드가 없고 필드를 계산할 수 없는 경우의 표현식 기본값입니다. 텍스트 정렬의 경우 텍스트 값을 지정해야 합니다. 숫자 정렬의 경우 숫자 값을 지정해야 합니다.	없음

다중 값 필드를 기준으로 정렬

특정 유형의 다중 값 필드를 기준으로 정렬할 때는 필드에 할당된 첫 번째 값만 사용됩니다. 예를 들어 DocA와 DocB의 두 문서에 모두 'color'라는 텍스트 필드가 있다고 가정해 보겠습니다. DocA의 'color' 필드에 두 값이(red, blue) 순서대로 할당되어 있고 DocB에 두 값이(green, red) 순서대로 할당되어 있습니다. 텍스트 필드 "color"를 지정하여 정렬을 수행하면 DocA는 "red"값으로, DocB는 '"green"값으로 정렬됩니다. 다른 필드 값은 정렬에 사용되지 않습니다.

정렬 여부 결정

정렬 옵션을 지정하지 않으면 검색 결과가 자동으로 내림차순으로 정렬되어 반환됩니다. 이 경우에는 반환되는 문서 수에 제한이 없습니다. 정렬 옵션을 지정하면 일치하는 모든 문서가 선택된 후에 정렬이 수행됩니다. 정렬의 크기를 제어하는 명시적 속성인 `SortOptions.limit`가 있습니다. 10,000개를 초과하는 문서를 정렬할 수 없으며 기본값은 1,000입니다. 일치하는 문서의 수가 `SortOptions.limit`로 지정된 수보다 많으면 검색에서 해당하는 제한된 개수만 검색, 정렬, 반환합니다. 이때 내림차순으로 표시된 일치하는 모든 문서 목록에서 정렬할 문서가 선택됩니다. 정렬할 수 있는 개수보다 더 많은 수의 일치하는 문서가 쿼리를 통해 선택될 수도 있습니다. 정렬 옵션을 사용하며 일치하는 모든 문서를 검색하는 것이 중요할 경우, 정렬할 수 있는 것보다 더 많은 문서가 쿼리를 통해 반환되지 않도록 해야 합니다.

표현식 쓰기

표현식은 필드 표현식('QueryOptions'에 설정됨) 및 정렬 표현식(SortOptions에 설정됨)을 정의하는 데 사용됩니다. 표현식은 문자열로 작성됩니다.

"price * quantity"
"(men + women)/2"
"min(daily_use, 10) * rate"
"snippet('rose', flower, 120)"

숫자 필드를 포함하는 표현식에는 산술 연산자(+, -, *, /)와 아래에 나열된 기본 제공 숫자 함수를 사용할 수 있습니다. 지리 좌표 필드를 포함하는 표현식은 지리 좌표 및 거리 함수를 사용할 수 있습니다. 텍스트 및 HTML 필드용 표현식에는 스니펫 함수를 사용할 수 있습니다.

표현식에 다음과 같은 특수 용어를 포함할 수도 있습니다.

용어	설명
`_rank`	문서의 순위 속성입니다. 필드 표현식 및 정렬 표현식에 사용할 수 있습니다.
`_score`	`SortOptions` 에서 `MatchScorer`를 포함하면 문서에 할당되는 점수입니다. 이 용어는 정렬 표현식에만 나타날 수 있으며 필드 표현식에는 사용할 수 없습니다.

숫자 함수

FieldExpressions 및 SortExpressions의 숫자 값을 정의하는 표현식에는 다음과 같은 기본 제공 함수를 사용할 수 있습니다. 인수는 숫자, 필드 이름이거나 숫자 및 필드 이름을 사용하는 표현식이어야 합니다.

함수	설명	예
`max`	가장 큰 인수를 반환합니다.	`max(recommended_retail_price, discount_price, wholesale_price)`
`min`	가장 작은 인수를 반환합니다.	`min(height, width, length)`
`log`	자연 로그를 반환합니다.	`log(x)`
`abs`	절댓값을 반환합니다.	`abs(x)`
`pow`	두 개의 숫자 인수를 사용합니다. pow(x, y) 호출은 x의 y 제곱 값을 계산합니다.	`pow(x, 2)`
`count`	필드 이름을 인수로 사용합니다. 문서에서 해당 이름이 지정된 필드의 수를 반환합니다. 문서에는 이름이 같지만 유형은 서로 다른 여러 필드가 포함될 수 있습니다. 참고: `count`는 `FieldExpressions`에서만 사용할 수 있으며, `SortExpressions`에는 표시되지 않습니다.	`count(user)`

지리 좌표 함수

지리 좌표 필드를 포함하는 표현식에 다음 함수를 사용할 수 있습니다.

함수	설명	예
`geopoint`	위도와 경도가 있는 지리 좌표를 정의합니다.	`geopoint(-31.3, 151.4)`
`distance`	두 지리 좌표 간의 거리를 미터 단위로 계산합니다. 두 인수 중 하나는 지리 좌표 필드의 이름이거나 지리 좌표 함수의 호출일 수 있습니다. 하지만 하나의 인수만 필드 이름이 될 수 있습니다.	`distance(geopoint(23, 134), store_location)`

스니펫

스니펫은 쿼리 문자열과 일치하며 주변 텍스트를 포함하는 텍스트 필드의 일부입니다. snippet 함수를 호출하여 스니펫을 만듭니다.

snippet(query, body, [max_chars])

query: 필드에서 찾을 텍스트를 지정하는 따옴표가 붙은 쿼리 문자열입니다.
body: 텍스트, HTML, Atom 필드의 이름입니다.
max_chars: 스니펫에 반환할 최대 문자 수입니다. 이 인수는 선택사항이며, 기본값은 160자입니다(영문 기준).

이 함수는 HTML 문자열을 반환합니다. 이 문자열에는 본문 필드 값의 스니펫이 포함되며, 쿼리와 일치하는 텍스트가 굵게 표시됩니다.