Google Cloud Search 架构采用 JSON 结构, 为数据编制索引以及查询数据的对象、属性和选项。 内容连接器会从存储区中读取数据,并根据 注册的架构、数据结构和索引。
您可以通过向 API 提供一个 JSON 架构对象,然后注册该对象来创建架构。在将数据编入索引之前,必须先为每个存储区注册一个架构对象。
本文档介绍了创建架构方面的基础知识。如欲了解如何调整架构以改善搜索体验,请参阅提高搜索质量。
创建架构
下面列出了创建 Cloud Search 架构所需执行的步骤:
。确定预期用户行为
预测用户执行的查询类型有助于引导您制定架构创建策略。
例如,在针对电影数据库发出查询时,您可能预测用户会执行诸如“显示由 Robert Redford 主演的所有电影”之类的查询。因此,您的架构必须支持根据“特定演员参演的所有电影”条件查询所得的结果。
要定义架构以反映用户的行为模式,建议执行以下任务:
- 评估不同用户所需的各种查询。
- 确定查询中可能使用的对象。对象是指相关数据的逻辑集合,例如电影数据库中的电影。
- 确定构成对象的属性和值, 查询中使用的语言。 属性是指对象的可编入索引的属性; 它们可以包含原始值或其他对象。 例如,电影对象可能具有电影标题和 作为原始值。电影对象还可能包含其他对象(例如演员),这些对象具有各自的属性(例如其姓名或角色)。
- 确定属性的示例有效值。值是指为属性编入索引的实际数据。例如,电影数据库可能包含一部名为“夺宝奇兵”(Raiders of the Lost Ark) 的电影。
- 确定用户所需的排序和排名选项。例如,在查询电影时,用户可能希望按时间顺序排列查询结果并按收视率进行排名,而不需要按标题的字母顺序排序。
- (可选)考虑您的某个属性是否代表 可能会执行搜索的情境,例如用户的职位 以便根据特定部门或部门 上下文。例如,如果用户搜索的是电影数据库 只对特定类型的电影感兴趣。用户可以定义 他们希望搜索后能返回的搜索结果类型 个人资料。然后,当用户开始输入有关电影的查询时, 仅限其首选类型的电影(例如“动作片”)建议为 部分自动填充建议。
- 创建一份可在搜索中使用的对象、属性和示例值列表(如需详细了解如何使用此列表, 请参阅定义运算符选项部分)。
初始化数据源
数据源表示存储区中已编入索引并存储在 Google Cloud 中的数据。有关初始化数据源的说明 参阅 管理第三方数据源。
用户的搜索结果通过数据源返回。当用户点击搜索结果时,Cloud Search 会使用索引请求中提供的网址将用户定向到实际项。
定义对象
在架构中,基本数据单元是对象(也称为“架构对象”),它表示数据的逻辑结构。在电影数据库中, 数据的逻辑结构是“movie”。另一个对象可能是“person”更改为 代表电影中参与的演职人员。
架构中的每个对象都有一系列用于描述该对象的属性或特性,例如 movie 对象具有标题和时长属性,而 person 对象具有姓名和生日属性。对象的属性可以包含原始值或其他对象。
图 1 显示了 movie 和 person 对象以及相关属性。
![实体间的架构连接图](https://developers.google.cn/static/cloud-search/images/schemaExample.png?authuser=5&hl=nl)
Cloud Search 架构是指
实质上是
objectDefinitions
标记之间。以下架构代码段显示了
movie 和 person 架构对象对应的 objectDefinitions
语句。
{
"objectDefinitions": [
{
"name": "movie",
...
},
{
"name": "person",
...
}
]
}
定义架构对象时,您需要为该对象提供 name
,该对象必须
是架构中所有其他对象中唯一的通常,您将使用 name
用于描述该对象的值(例如,对于 movie 对象,该属性为 movie
)。架构
服务将 name
字段用作可编入索引的对象的键标识符。对于
有关 name
字段的更多信息,请参阅
对象定义。
定义对象属性
如
ObjectDefinition,
对象名称后跟一组
options
,
以及一系列
propertyDefinitions
。
通过
options
可以
进一步包含
freshnessOptions
和
displayOptions
。
通过
freshnessOptions
用于根据项的新鲜度调整搜索排名。通过
displayOptions
用于定义特定标签和属性是否以
某个对象的搜索结果。
通过
propertyDefinitions
部分用于定义对象的属性,例如电影标题
以及发布日期
以下代码段显示了具有两个属性的 movie
对象:movieTitle
和 releaseDate
。
{
"objectDefinitions": [
{
"name": "movie",
"propertyDefinitions": [
{
"name": "movieTitle",
"isReturnable": true,
"isWildcardSearchable": true,
"textPropertyOptions": {
"retrievalImportance": { "importance": "HIGHEST" },
"operatorOptions": {
"operatorName": "title"
}
},
"displayOptions": {
"displayLabel": "Title"
}
},
{
"name": "releaseDate",
"isReturnable": true,
"isSortable": true,
"datePropertyOptions": {
"operatorOptions": {
"operatorName": "released",
"lessThanOperatorName": "releasedbefore",
"greaterThanOperatorName": "releasedafter"
}
},
"displayOptions": {
"displayLabel": "Release date"
}
...
]
}
]
}
PropertyDefinition 包含以下几项:
name
字符串。- 不限定类型的选项列表,例如上述示例中的
isReturnable
代码段。 - 类型及其关联的专用选项;
例如上一个代码段中的
textPropertyOptions
和retrievalImportance
。 - 一个
operatorOptions
,用于说明该属性如何用作 搜索运算符。 - 一个或多个
displayOptions
,例如上一个代码段中的displayLabel
。
属性的 name
在所属对象中必须是唯一的,
但同样的名称可以用于其他对象和子对象。
在图 1 中,电影的标题和发布日期定义了两次:
在 movie
对象中执行一次,在filmography
person
对象。此架构重复使用了 movieTitle
字段
以便架构可以支持两种类型的搜索行为:
- 当用户搜索电影的标题时,显示电影搜索结果。
- 当用户搜索由某演员参演的电影的标题时,显示演职人员搜索结果。
同样,该架构会重复使用 releaseDate
字段,因为它具有相同的
两个 movieTitle
字段的含义。
在开发自己的架构时,建议考虑采用何种方式可能会使存储区中具有相关字段,而这些字段包含要在架构中声明多次的数据。
添加不限定类型的选项
PropertyDefinition 会列出所有属性都通用的常规搜索功能选项,无论数据类型如何。
isReturnable
- 指明属性是否标识了应该 。电影示例 属性是否可返回。不可返回值的属性可用于搜索结果或对结果进行排名,但不会返回给用户。isRepeatable
- 表示属性是否允许使用多个值。例如,一部电影只能有一个发布日期,但可以有多名演员。isSortable
- 表示该属性可用于排序。对于可重复的属性,此选项不能为 true。例如,搜索到的电影结果可以按发布日期或收视率排序。isFacetable
- 表示该属性可用于生成构面。 Facet 用于优化搜索结果,使用户能够看到 初始结果,然后添加条件或构面,以进一步优化 结果。对于类型为“对象”且isReturnable
必须为 true 才能设置此选项。最后,这个选项 支持枚举、布尔值和文本属性。 例如,在我们的示例架构中,genre
、actorName
、userRating
和mpaaRating
可分面,允许他们执行以下操作: 用于以交互方式优化搜索结果。isWildcardSearchable
表示用户可以对以下内容执行通配符搜索: 此属性中。此选项仅适用于文本属性。通配符的工作原理 取决于文本字段中设置的值, exactMatchWithOperator 字段。如果exactMatchWithOperator
设置为true
, 文本值被标记化为一个原子值,通配符搜索 对它执行的操作例如,如果文本值为science-fiction
, 通配符查询science-*
与之匹配。如果exactMatchWithOperator
设置为false
:对文本值进行词法单元化处理,并针对 每个词元。例如,如果文本值为“science- Fitbit”,则通配符 查询sci*
或fi*
与项目匹配,但science-*
不匹配。
这些常规搜索功能参数均为布尔值;他们
所有行的默认值都是 false
,并且必须设置为 true
使用。
下表显示了设置为 true
的布尔值参数
为 movie
对象的所有属性指定以下值:
属性 | isReturnable |
isRepeatable |
isSortable |
isFacetable |
isWildcardSearchable |
---|---|---|---|---|---|
movieTitle |
true | true | |||
releaseDate |
true | true | |||
genre |
true | true | true | ||
duration |
true | ||||
actorName |
true | true | true | true | |
userRating |
true | true | |||
mpaaRating |
true | true |
genre
和 actorName
的 isRepeatable
均设置为 true
因为一部电影可能属于多个类型,并且通常具有
多个演员。如果某个属性是可重复的属性或包含在可重复的子对象中,则该属性不能用于排序。
定义类型
通过
PropertyDefinition
reference 部分列出了几个 xxPropertyOptions
,其中 xx
是特定类型,
例如 boolean
。要设置属性的数据类型,您必须定义适当的数据类型对象。为属性定义数据类型对象即会确立该属性的数据类型。例如,定义
movieTitle
属性的 textPropertyOptions
表示电影
title 的类型为文本。以下代码段显示了 movieTitle
属性
并使用 textPropertyOptions
设置数据类型。
{
"name": "movieTitle",
"isReturnable": true,
"isWildcardSearchable": true,
"textPropertyOptions": {
...
},
...
},
一个属性只能有一个关联的数据类型。例如,在我们的电影中,
架构,releaseDate
只能是日期(例如,2016-01-13
)或字符串
(例如,January 13, 2016
),但不能同时设置这两者。
以下数据类型对象用于为示例电影架构中的属性指定数据类型:
属性 | 数据类型对象 |
---|---|
movieTitle |
textPropertyOptions |
releaseDate |
datePropertyOptions |
genre |
enumPropertyOptions |
duration |
textPropertyOptions |
actorName |
textPropertyOptions |
userRating |
integerPropertyOptions |
mpaaRating |
textPropertyOptions |
您为属性选择的数据类型取决于您的预期用例。
在此电影架构的虚构场景中,用户应
按时间顺序对结果进行排序,因此 releaseDate
是一个日期对象。
例如,如果预期用例是比较 12 月份的版本
那么使用字符串格式可能会很有用。
配置类型特有的选项
PropertyDefinition 参考部分提供了适用于每种类型的选项。最特定于类型的
选项都是可选的,但possibleValues
enumPropertyOptions
。此外,通过 orderedRanking
选项,您还可以
对各个值进行排名。通过
以下代码段显示了具有 textPropertyOptions
的 movieTitle
属性
设置数据类型,并使用 retrievalImportance
类型专用选项。
{
"name": "movieTitle",
"isReturnable": true,
"isWildcardSearchable": true,
"textPropertyOptions": {
"retrievalImportance": { "importance": "HIGHEST" },
...
},
...
}
以下是示例架构中使用的其他类型特有选项:
属性 | 类型 | 类型特有选项 |
---|---|---|
movieTitle |
textPropertyOptions |
retrievalImportance |
releaseDate |
datePropertyOptions |
|
genre |
enumPropertyOptions |
|
duration |
textPropertyOptions |
|
actorName |
textPropertyOptions |
|
userRating |
integerPropertyOptions |
orderedRanking 、maximumValue |
mpaaRating |
textPropertyOptions |
定义运算符选项
除了类型特有选项之外,每种类型还有一组可选的
operatorOptions
这些选项描述的是如何将属性用作
搜索运算符。以下代码段显示了具有movieTitle
textPropertyOptions
:设置数据类型,并使用
retrievalImportance
和 operatorOptions
类型专用选项。
{
"name": "movieTitle",
"isReturnable": true,
"isWildcardSearchable": true,
"textPropertyOptions": {
"retrievalImportance": { "importance": "HIGHEST" },
"operatorOptions": {
"operatorName": "title"
}
},
...
}
每个 operatorOptions
都有一个 operatorName
,比如 title
表示
movieTitle
。运算符名称是属性的搜索运算符。搜索运算符是您预期用户在缩小搜索范围时使用的实际参数。例如,要根据片名搜索电影,
用户可以输入 title:movieName
,其中 movieName
是电影的名称。
运算符名称不必与属性名称相同,而是应该能够反映组织中的用户最常用的词语。例如,如果您的用户更喜欢使用“name”而不是“title”来表示电影标题,则应将运算符名称设置为“name”。
您可以对多个属性使用相同运算符名称,前提是所有属性都解析为相同类型。在查询期间使用共有的运算符名称时,系统将检索使用该运算符名称的所有属性。例如:
假设 movie 对象具有 plotSummary
和 plotSynopsis
属性,其中每个属性的 operatorName
均为 plot
。如
只要这两个属性都是文本 (textPropertyOptions
),单个
使用 plot
搜索运算符执行查询,则二者均可检索。
除了 operatorName
之外,可排序的属性还可以
operatorOptions
中的 lessThanOperatorName
和 greaterThanOperatorName
字段。
用户可以使用这些选项来根据与
提交的值。
最后,textOperatorOptions
中有一个 exactMatchWithOperator
字段,
operatorOptions
。如果您
将 exactMatchWithOperator
设置为 true
,则查询字符串必须
与整个属性值匹配,而不仅仅是在文本中找到。
文本值在运算符搜索中被视为一个原子值,并且
构面匹配。
例如,考虑将具有 genre 属性的 Book 或 Movie 对象编入索引。
类型可以包括“Science-Fiction”、“Science”和“Fiction”。包含
将 exactMatchWithOperator
设置为 false
或省略,
搜索某个流派或
选择“科学”或“小说”Facet 还会
返回“Science-Fiction”的搜索结果因为文本经过词元化处理,
“科学”和《小说》词元数量。
当 exactMatchWithOperator
为 true
时,
文本被视为单个词元,
“科学”或“小说”匹配“Science-Fiction”。
(可选)添加 displayOptions
部分
任何链接的末尾都有一个可选的 displayOptions
部分。
propertyDefinition
部分。此部分包含一个 displayLabel
字符串。
displayLabel
是一个建议采用且易于使用的文本标签
。如果媒体资源已配置为使用
ObjectDisplayOptions,
此标签将显示在属性的前面。如果已配置媒体资源
且未定义 displayLabel
,则只有属性值
。
以下代码段显示了具有 displayLabel
的 movieTitle
属性
设置为“标题”。
{
"name": "movieTitle",
"isReturnable": true,
"isWildcardSearchable": true,
"textPropertyOptions": {
"retrievalImportance": { "importance": "HIGHEST" },
"operatorOptions": {
"operatorName": "title"
}
},
"displayOptions": {
"displayLabel": "Title"
}
},
以下是 movie
的所有属性的 displayLabel
值
对象:
属性 | displayLabel |
---|---|
movieTitle |
Title |
releaseDate |
Release date |
genre |
Genre |
duration |
Run length |
actorName |
Actor |
userRating |
Audience score |
mpaaRating |
MPAA rating |
(可选)添加“suggestionFilteringOperators[]
”部分
您可以
suggestionFilteringOperators[]
部分propertyDefinition
。使用此部分可执行以下操作:
定义用于过滤自动补全建议的属性。例如,您
可以定义 genre
的运算符,以根据用户的
首选电影类型。然后,当用户输入搜索查询时
符合其首选类型的电影会在自动补全中显示
建议。
注册架构
要使 Cloud Search 查询返回结构化数据,您必须将您的架构注册到 Cloud Search 架构服务中。要注册架构,您需要提供在初始化数据源步骤中获取的数据源 ID。
使用该数据源 ID 发出 UpdateSchema 请求,即可注册您的架构。
发出以下 HTTP 请求以注册您的架构(详情见 UpdateSchema 参考页面):
PUT https://cloudsearch.googleapis.com/v1/indexing/{name=datasources/*}/schema
您的请求正文应包含以下内容:
{ "validateOnly": // true or false, "schema": { // ... Your complete schema object ... } }
使用 validateOnly
选项可在不使用的情况下测试架构的有效性
注册该 API
将数据编入索引
注册架构后,请使用索引调用填充数据源。索引编制操作通常在内容连接器中完成。
对于电影架构,针对单部电影的 REST API 索引请求如下所示:
{
"name": "datasource/<data_source_id>/items/titanic",
"acl": {
"readers": [
{
"gsuitePrincipal": {
"gsuiteDomain": true
}
}
]
},
"metadata": {
"title": "Titanic",
"sourceRepositoryUrl": "http://www.imdb.com/title/tt2234155/?ref_=nv_sr_1",
"objectType": "movie"
},
"structuredData": {
"object": {
"properties": [
{
"name": "movieTitle",
"textValues": {
"values": [
"Titanic"
]
}
},
{
"name": "releaseDate",
"dateValues": {
"values": [
{
"year": 1997,
"month": 12,
"day": 19
}
]
}
},
{
"name": "actorName",
"textValues": {
"values": [
"Leonardo DiCaprio",
"Kate Winslet",
"Billy Zane"
]
}
},
{
"name": "genre",
"enumValues": {
"values": [
"Drama",
"Action"
]
}
},
{
"name": "userRating",
"integerValues": {
"values": [
8
]
}
},
{
"name": "mpaaRating",
"textValues": {
"values": [
"PG-13"
]
}
},
{
"name": "duration",
"textValues": {
"values": [
"3 h 14 min"
]
}
}
]
}
},
"content": {
"inlineContent": "A seventeen-year-old aristocrat falls in love with a kind but poor artist aboard the luxurious, ill-fated R.M.S. Titanic.",
"contentFormat": "TEXT"
},
"version": "01",
"itemType": "CONTENT_ITEM"
}
请注意 objectType
字段中 movie
的值如何与对象匹配
架构中的定义名称。通过匹配这两个值,Cloud Search 可以了解索引编制期间要使用的架构对象。
另请注意架构属性 releaseDate
的索引编制如何使用
year
、month
和 day
的子属性。
date
数据类型(通过使用 datePropertyOptions
来定义)。
不过,由于架构中未定义 year
、month
和 day
,
无法查询其中某个属性(例如year
)。
另外,请注意如何使用列表将可重复属性 actorName
编入索引
值。
识别潜在的索引问题
以下是与架构和索引相关的两大最常见问题:
您的索引请求包含未向架构服务注册的架构对象或属性名称。此问题会导致该属性或对象被忽略。
索引请求中属性的类型值不同于架构中注册的类型。此问题会导致 Cloud Search 在编制索引时返回错误。
使用多种查询类型测试架构
在注册您的架构以将其用于大型生产数据存储区之前,建议先使用一个小型测试数据存储区对其进行测试。通过使用小型测试存储区测试架构,您可以快速对架构作出调整并删除已编入索引的数据,而不会影响大型索引或现有生产索引。对于测试数据存储区,建议创建一个仅向测试用户提供授权的 ACL,以使其他用户不会在搜索结果中看到此数据。
要创建用于验证搜索查询的搜索界面,请参阅搜索界面。
本部分包含可用于测试电影架构的几个不同示例查询。
使用通用查询进行测试
通用查询返回数据源中包含特定字符串的所有项。您可以在搜索界面中输入“titanic”一词并按 Return 键对电影数据源运行通用查询。搜索结果中应该会返回所有带有“titanic”字样的电影。
使用运算符进行测试
在查询中添加运算符可将结果限制为与该运算符值匹配的项。例如,您可能想要使用 actor
运算符来查找
由特定演员主演的所有电影。利用搜索界面,您可以执行下列操作
只需输入 operator=value 对,即可执行此运算符查询,例如
"actor:Zane",然后按 "actor:Zane" 键。搜索结果中应该会返回 Zane 参演的所有电影。
调整架构
在您的架构和数据被使用之后,您可以继续监控哪些对您的用户有用,哪些对他们无用。对于以下情况,建议您适当调整架构:
- 将尚未编入索引的字段编入索引。例如,您的用户可能会根据导演姓名反复搜索电影,因此您可以调整架构以支持使用导演姓名作为运算符。
- 根据用户反馈更改搜索运算符名称。运算符名称应该是简单易懂的。如果您的用户总是“记错”运算符名称,建议您更改此名称。
架构更改后重新编制索引
更改架构中的以下任何值都不需要将数据重新编入索引。您只需要提交新的 UpdateSchema 请求,您的索引将继续有效:
- 运算符名称。
- 整数类型的最小值和最大值。
- 按整数值和枚举值排序的排名。
- 新鲜度选项。
- 显示选项。
对于以下更改,先前已编入索引的数据将继续根据先前注册的架构工作。但是,如果更新后的架构发生了以下更改,则现有条目必须重新编入索引,这些更改才能体现在该架构中:
- 添加新的属性或对象,或者移除现有属性或对象
- 正在将
isReturnable
、isFacetable
或isSortable
从false
更改为true
。
只有在以下情况下,您应将 isFacetable
或 isSortable
设置为 true
:
明确的应用场景和需求
最后,当您通过将属性标记为 isSuggestable
来更新架构时,
您必须将数据重新编入索引,这会导致在
相应属性。
不允许的属性更改
有些架构更改是不允许的,即使将数据重新编入索引也是如此,因为这些更改会破坏索引,或者产生不良或不一致的搜索结果。具体包括对以下项的更改:
- 属性数据类型。
- 属性名称。
exactMatchWithOperator
设置。retrievalImportance
设置。
但是,有一种方法可以解决该限制。
对架构进行复杂更改
为避免会导致搜索结果不佳或搜索索引损坏的更改,Cloud Search 会在存储区被编入索引后阻止 UpdateSchema 请求中的某些类型更改。例如,属性的数据类型或名称在设置后即无法更改。这些更改 无法通过简单的 UpdateSchema 请求的数据,即使您将数据重新编入索引也是如此。
如果您必须对架构进行其他不允许的更改,通常可以通过执行一系列允许的更改来实现相同效果。一般来说,这需要先将已编入索引的属性从旧对象定义迁移到较新的对象定义,然后发送一个仅使用较新属性的索引请求。
以下步骤展示了如何更改属性的数据类型或名称:
- 在架构的对象定义中添加新属性。请使用与要更改的属性不同的名称。
- 使用新定义发出 UpdateSchema 请求。请务必在请求中发送整个架构,包括新旧属性。
从数据存储区回填索引。要回填索引,请使用新属性发送所有索引请求,而不要使用旧属性,否则会导致将查询匹配项重复统计两次。
- 在索引回填期间,检查新属性并默认使用旧属性,以免出现不一致的行为。
- 回填完成后,运行测试查询以进行验证。
删除旧属性。再次发出 UpdateSchema 请求但不带旧属性名称,并且在以后的索引请求中停止使用旧属性名称。
将旧属性的所有用例都迁移到新属性。例如,如果您将属性名称从 creator 更改为 author,则必须更新查询代码才能在之前引用 creator 的地方使用 author。
Cloud Search 会将所有已删除的属性或对象的记录保留 30 天 以防出现任何可能导致意外索引结果的重复使用。 在这 30 天内,您应停止使用已删除的 包括在以后的索引请求中将其省略。 这样可以确保您以后决定恢复该属性或 对象,您可以采用保持索引正确性的方式执行此操作。
了解大小限制
Cloud Search 对结构化数据对象和架构的大小施加了限制。 具体限制如下:
- 顶层对象的数量不得超过 10 个。
- 结构化数据层次结构的深度不得超过 10 级。
- 对象中的字段总数不得超过 1000 个,其中包括原始字段的数量以及各嵌套对象中的字段总数。
后续步骤
以下是您后续可执行的几个步骤:
创建一个搜索界面来测试您的架构。
调整架构以提高搜索质量。
了解如何利用 需要定义的
_dictionaryEntry
架构 公司常用术语的同义词。要使用_dictionaryEntry
请参阅 定义同义词。创建连接器。