查询字符串包含 Unicode 字符。查询字符串的长度上限为 2000 个字符。所有查询字符串都包含至少一个字段值。建议用小写字母书写字段值，因为对 Atom、文本和 HTML 字段的搜索不区分大小写，并且查询字符串也可能包含布尔运算符 AND、OR 和 NOT，这些运算符用大写字母书写以示区分。
英文逗号仅在以下两种情况下才可以出现在查询字符串中：用于分隔函数参数 (distance(home, geopoint(35.2, 40.5)) > 100)，或者属于用英文引号括住的字符串的一部分。
查询字符串可采用多种形式。构建查询主要有两种方式：使用字段名称和不使用字段名称。“全局搜索”使用仅包含字段值的查询字符串：
String query = "blue";
String query = "NOT white";
String query = "blue OR red";
String query = "blue guitar";
“字段搜索”使用的查询字符串包含一个或多个指定了字段名称和字段值的表达式。
String query = "model:gibson date < 1965-01-01";
String query = "title:\"Harry Potter\" AND pages<500";
String query = "beverage:wine color:(red OR white) NOT country:france";
本文档介绍了如何为全局搜索和字段搜索构建查询字符串，以及搜索逻辑在每种情况下的工作原理。
如果您想保留已执行查询的记录，我们建议在应用中记录查询字符串。
全局搜索
借助全局搜索，您可以指定可能出现在任何文档字段中的值，以此来搜索文档。要执行全局搜索，您需要编写包含一个或多个字段值的查询字符串。搜索算法会识别每个值的类型，并搜索可能包含该值的所有文档字段。
单值查询
使用包含单个值的查询字符串进行的搜索将根据以下规则进行处理：
如果查询字符串是单词 (red) 或带英文引号的字符串 ("red rose")，则将在索引中检索具有以下内容的所有文档：
- 包含该单词或带英文引号的字符串的文本或 HTML 字段（不区分大小写）。
- 值与该单词或带英文引号的字符串相匹配的 Atom 字段（不区分大小写）。
如果查询字符串是数字（“3.14159”），则搜索将检索具有以下内容的所有文档：
- 包含与查询中所示数字匹配的词元的文本或 HTML 字段（文本字段“he took 5 minutes”将与查询“5”匹配，但与“5.0”不匹配）。
- 与查询中所示数字字面相匹配的 Atom 字段。
如果查询字符串是 yyyy-mm-dd 格式的日期，则搜索将检索具有以下内容的所有文档：
- 值等于所查询日期的日期字段（查询字符串中的前导零是可选的，“2012-07-04”和“2012-7-4”表示同一日期）。
- 包含与查询中所示日期字面匹配的词元的文本或 HTML 字段。
- 与查询中所示日期字面匹配的 Atom 字段。
您可以将 NOT 布尔运算符（大写）添加到只含一个单词的查询中。根据相同规则，您将会得到不含任何与查询值匹配的字段的文档列表。也就是说，查询 NOT red 检索到的所有文档都没有任何包含“red”的文本或 HTML 字段，或者任何值为 red 的 Atom 字段。
您可能已经注意到，上文并未提及 geopoint 字段。目前，您无法将原始 geopoint 值指定为字符串，因此地理坐标点无法显示在全局搜索中。
多值查询
您可以在全局搜索字符串中指定多个值（以空格分隔）。单词、带英文引号的字符串、数字和日期之间的空格被视为隐式 AND 运算符。下面两个搜索字符串几乎相同；区别在于全局搜索处理 Atom 字段的方式不同，具体如下所述：
query = "small red"
query = "small AND red"
当使用多个值执行全局搜索时，字段匹配是针对字符串中的每个值单独完成的，但 Atom 字段匹配的处理方式不同，特别是：
- 查询值可以在文本或 HTML 字段中以任意顺序出现。
- 不同的值可以出现在不同的字段中。
- 仅当查询字符串不包含任何布尔运算符时（
AND、OR和NOT），才会搜索 Atom 字段。整个查询字符串必须与 Atom 字段匹配。
请注意处理 Atom 字段的第三条规则。查询字符串“red small”不包含布尔运算符 AND（尽管隐式包含此运算符），因此将尝试查找匹配的 Atom 字段。字符串“red AND small”包含一个布尔运算符，因此搜索功能不会尝试将此查询字符串与 Atom 字段进行匹配。
以下示例展示了使用查询字符串“rose bud”检索到的四个文档。每个文档都有两个文本字段和一个 Atom 字段。备注列说明了每个文档符合查询条件的原因。
| 文档 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 字段的完整内容必须与查询值匹配，这包括字段中的任何 Unicode 组合字符或重音字符。Atom 字段不支持词干提取。
| 查询字符串 | 备注 |
|---|---|
"weather=stormy"
|
两种形式的等式运算符均有效。检索包含“weather”字段且该字段显示“stormy”的文档。 |
"Title: \"Tom&Jerry\""
|
如果要搜索包含空格或特殊字符的 Atom 字段，请用英文引号括住值。 |
"Color = (red OR blue)"
|
您可以使用英文括号和逻辑运算符 OR 来指定备用字段值的列表。 |
对文本字段和 HTML 字段的查询
对于文本字段和 HTML 字段，唯一有效的关系运算符是等式运算符。在这种情况下，该运算符的含义是“字段包含值”而不是“字段等于值”。您可以使用词干提取运算符来搜索单词的变体。您还可以使用 OR 和 AND 运算符为字段值指定复杂的布尔表达式。如果布尔运算符出现在用引号括住的字符串中，则不会受到特殊对待，它只是待匹配字符串的一部分。请注意，在搜索 HTML 字段时，系统会忽略 HTML 标识标记中的文本。对文本字段和 HTML 字段的查询不区分大小写。将这些字段编入索引时，字段中的任何 Unicode 组合字符与重音字符将“标准化”为未加重音的字符。在针对这些字段的查询字符串中，组合字符和重音字符也将标准化，因此无论查询是否包含重音形式，均不影响字段的匹配。
| 查询字符串 | 备注 |
|---|---|
"Comment = great" |
两种形式的等式运算符均有效。检索带有“Comment”字段，且该字段中至少出现一次单词“great”的文档。 |
"Comment = (great big ball)"
|
要在字段中搜索两个或更多单词，且对单词的出现顺序没有要求，请用英文括号将单词括起来。此查询字符串检索符合以下条件的文档：带有“Comment”字段，且该字段中包含所有这三个要查询的单词，而不论这些单词以何种顺序出现以及中间有多少个其他单词。单词之间的空格表示逻辑 AND；第二种形式使该逻辑运算符变为显式。 |
"Comment = \"insanely great\""
|
如需搜索特定文本字符串，请用英文引号将字符串引起来。此查询会检索那些“Comment”字段中包含词组“insanely great”（以及经词法单元化后具有等同意义的词组“insanely-great”）的文档。 |
"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 嵌入带英文引号的字符串中，因此不会将其视为关系运算符。此查询字符串检索具有“weather”字段且该字段中包含字符串“rain or shine”的文档。 |
对数字字段的查询
数字字段值可以是整数、小数或指数。数字字段的有效关系运算符是等式运算符，以及小于/大于运算符（<、<=、> 和 >=）。请注意，不包括不等式 (!=) 运算符。下面是数字字段的一些查询字符串示例：
"quantity = 10000"
"size: 4"
"price < 9.99"
"theta > 1.5E-2"
对日期字段的查询
日期字段值必须采用 yyyy-mm-dd form 编写。前导零对于一位数月份和日期而言不是必需的。日期字段的有效关系运算符是等式运算符，以及小于/大于运算符（<、<=、> 和 >=）。请注意，不包括不等式运算符。您可以在表达式前添加 NOT 运算符，以对该表达式执行求反运算。下面是日期字段的一些查询字符串示例：
"start_date: 2012-05-20"
"end_date: 2013-5-1"
"birthday >= 2000-12-31"
"NOT birthday = 2000-12-25"
对 geopoint 字段的查询
Geopoint 字段不能使用任何关系运算符，因此无法在查询字符串中直接指定 geopoint 字段。Search API 提供两个特殊的函数，可用于包含 geopoint 字段的查询：
geopoint(lat,long)- 指定具有明确经度和纬度的地理坐标点。
distance(point1, point2)- 计算两个地理坐标点之间的距离（以米为单位）。要指定各点，可以使用地理坐标点字段的名称或调用 geopoint 函数。请注意，您不能将两个字段名称作为参数提供给此函数。必须至少有一个参数是常量。
用这些函数构建的查询可用于检索基于常量位置进行定位的地点。以下示例假设索引包含带有名为“survey_marker”和“home”的 geopoint 字段的文档。
| 查询字符串 | 备注 |
|---|---|
"distance(survey_marker, geopoint(35.2, 40.5)) < 100" |
搜索距离给定地理坐标点不到 100 米的方位标。 |
"distance(home, geopoint(35.2, 40.5)) > 100" |
搜索距离给定地理坐标点超过 100 米的房屋。 |
使用地理定位的应用通常从浏览器接收信息。如果用户允许，可以根据他们的 IP 地址推断出他们的位置，或者他们可以输入邮政编码。位置信息也可以来自其他 API，如 Google Maps Geolocation 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”且“price”字段值小于 5000 的文档。AND 逻辑隐含其中，第二种形式与第一种等同。 |
"keyboard OR product=piano" |
检索“product”字段包含“piano”的文档，或任何文本、HTML 或 Atom 字段包含“keyboard”的文档。 |