Google Cloud Search 結構定義是一種 JSON 結構,可以定義 物件、屬性和選項,可用於建立索引及查詢資料。 內容連接器會讀取存放區中的資料,並根據您的 註冊結構定義、結構和索引
您可以提供 JSON 結構定義物件給 API,以建立結構定義 再進行註冊您必須註冊結構定義物件 ,才能為資料建立索引。
本文說明結構定義建立機制的基本概念。如要瞭解 如要調整結構定義以提升搜尋體驗,請參閱 提升搜尋品質。
建立結構定義
以下是建立 Cloud Search 結構定義的步驟清單:
,瞭解如何調查及移除這項存取權。找出預期的使用者行為
預測使用者查詢的類型有助於制定策略 建立結構定義
舉例來說,對電影資料庫發出查詢時,您預期的值可能會 使用者的查詢,例如「Show me all movies starring Robert Redford」(顯示小羅瑞德的所有電影)。 因此,您的結構定義必須支援以「含有 特定演員。」
如要根據使用者的行為模式定義結構定義,您可以考慮 來執行這些工作:
- 評估不同使用者所做的各種查詢。
- 識別可能在查詢中使用的物件。物件是邏輯性質 一組相關資料,例如電影資料庫中的電影。
- 找出構成物件的屬性和值 您在查詢中使用的按鈕 屬性是物件的可建立索引屬性; 可以包含原始值或其他物件 舉例來說,電影物件可能會有電影名稱、 發行日期做為原始值。電影物件也可能包含 物件 (例如演員) 擁有自己的屬性,例如 名稱或角色
- 找出屬性的有效值範例。值是實際資料 已編入索引例如資料庫中某一部電影的片名 「失蹤的鯊魚」
- 決定使用者所需的排序與排名選項。例如: 查詢電影時,使用者可能會想依時間順序排序 而且不需依標題的字母順序排列。
- (選用) 請思考你的其中一個房源是否代表更具體的 可能在哪個情境下執行搜尋,例如使用者的職務 如此,系統才會根據個人偏好提供自動完成建議 相關資訊舉例來說,如果使用者搜尋電影資料庫, 只對特定電影類型感興趣。使用者會定義 希望搜尋的內容類型 (可能是使用者的一部分) 然後,當使用者開始輸入電影查詢時 僅包含偏好內容類型的電影,例如「動作片」建議為 「自動完成建議」的一部分
- 列出可能有哪些物件、屬性和範例值 搜尋。(如要進一步瞭解這份清單的使用方式, 請參閱「定義運算子選項」一節)。
初始化資料來源
「資料來源」代表已建立索引存放區中的資料 並儲存在 Google Cloud 中如需初始化資料來源的操作說明 提及 管理第三方資料來源。
使用者的搜尋結果會從資料來源傳回。當使用者點選 Cloud Search 會利用搜尋結果頁面,將使用者導向實際的項目 索引要求中提供的網址。
定義物件
結構定義中的基本資料單位是物件,也稱為「結構定義 object」是一種資料邏輯結構,在電影資料庫中 資料的邏輯結構為「電影」另一個物件可能是「person」到 代表電影中的演員和工作人員
結構定義中的每個物件都各有一系列的「屬性」或「屬性」 描述物件,例如電影的名稱和持續時間,或名稱 使用者的出生日期和出生日期物件屬性可包含原始項目 值或其他物件
圖 1 顯示了電影和人物物件,以及相關聯的 資源。
![繪製實體之間的結構定義連結](https://developers-dot-devsite-v2-prod.appspot.com/static/cloud-search/images/schemaExample.png?authuser=7&hl=zh-tw)
Cloud Search 結構定義是
基本上是一組由
objectDefinitions
標記。下列結構定義程式碼片段顯示
電影和個人結構定義物件的 objectDefinitions
陳述式。
{
"objectDefinitions": [
{
"name": "movie",
...
},
{
"name": "person",
...
}
]
}
定義結構定義物件時,您需要為該物件提供 name
不得重複。通常會使用 name
值描述物件,例如電影物件的 movie
。結構定義
服務使用 name
欄位做為可建立索引物件的金鑰 ID。適用對象
如要進一步瞭解 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
- 表示屬性是否應識別應取得的資料 透過 Query API 傳回搜尋結果。所有範例電影 屬性都可供傳回。無法傳回的房源可能用於搜尋 或是決定排名,而不傳回使用者isRepeatable
- 表示屬性是否允許多個值。適用對象 例如,一部電影只有一個上映日期,但可以有多名演員。isSortable
- 表示屬性可用於排序。這個 不可為重複屬性傳回 true。舉例來說,電影搜尋結果 並按照推出日期或目標對象分級排序isFacetable
:表示屬性可用於產生「facet」。 facet 可用來縮小使用者看到的搜尋結果範圍 初始結果,然後加入條件 (或 facet) 以進一步縮小 也就是預測結果型別為物件且屬性為物件的屬性則無法設為 trueisReturnable
必須為 true,才能設定這個選項。最後,這個選項只會在 支援列舉、布林值和文字屬性 例如,在範例結構定義中genre
、actorName
、userRating
和mpaaRating
facetable 可讓您: 可用於互動式篩選搜尋結果。isWildcardSearchable
表示使用者可以使用萬用字元搜尋 這個屬性。這個選項僅適用於文字屬性。萬用字元的運作方式 搜尋作業是根據文字欄位中設定的值 exactMatchWithOperator 欄位。如果將exactMatchWithOperator
設為true
, 系統會將文字值代碼化為一個原子值,萬用字元搜尋為 沒有任何影響舉例來說,如果文字值為science-fiction
, 萬用字元查詢「science-*
」與這個查詢完全相符。如果將exactMatchWithOperator
設為false
,文字值會權杖化,並對萬用字元搜尋執行 各個權杖舉例來說,如果文字值為「science-cpm」,請使用萬用字元 查詢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
參考部分列出數個 xxPropertyOptions
,其中 xx
是特定類型
例如 boolean
如要設定屬性的資料類型,請
適當的資料類型物件定義屬性的資料類型物件
可建立該屬性的資料類型例如定義
movieTitle
屬性的 textPropertyOptions
代表電影
標題是文字類型以下程式碼片段顯示 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
。運算子名稱是屬性的搜尋運算子。A 罩杯
搜尋運算子是您希望使用者實際使用的參數
有助於縮小搜尋範圍舉例來說,如要依照電影名稱搜尋電影,
使用者輸入 title:movieName
,其中 movieName
是電影名稱。
運算子名稱不必與屬性名稱相同。 建議使用運算子名稱 反映最常出現在字詞中的 保護使用者舉例來說,如果使用者偏好 "name"而不是「title」則業者名稱應為 設定為「name」。
您可以針對多個屬性使用相同的運算子名稱,
所有屬性都會解析為相同類型。如果在使用期間使用共用運算子名稱
查詢時,系統會擷取所有使用該運算子名稱的屬性。例如:
假設電影物件包含 plotSummary
和 plotSynopsis
和每項屬性的 operatorName
皆為 plot
。阿斯
只要這兩種屬性都是文字 (textPropertyOptions
),
查詢則是同時擷取兩種字串。plot
除了 operatorName
之外,可排序的屬性可能會有
operatorOptions
中的 lessThanOperatorName
和 greaterThanOperatorName
欄位
使用者可以利用這些選項,根據與下列項目的比較結果建立查詢
提交的值
最後,textOperatorOptions
的 exactMatchWithOperator
欄位位於
operatorOptions
。如果發生以下情況:
將 exactMatchWithOperator
設為 true
,則查詢字串必須
符合整個屬性值,並非只在文字中找到。
在運算子搜尋與
facet 比對。
舉例來說,請考慮為含有類型屬性的「圖書」或「電影」物件建立索引。
類型可能包含「科學」、「科學」和「小說」。取代為
exactMatchWithOperator
已設為「false
」或省略,
搜尋類型
選取「科學」或「小說」facet 也會
傳回「Science-Fiction」的結果代碼化後
「科學」和「小說」符記都存在於「Science-Fiction」中
當 exactMatchWithOperator
為 true
時,
系統會將文字視為單一符記
「科學」或「小說」與「Science-Fiction」相符。
(選用) 新增「displayOptions
」部分
如有需要,您可以在任何結尾的 displayOptions
部分
「propertyDefinition
」專區。這個區段包含一個 displayLabel
字串。
建議使用 displayLabel
的文字標籤,容易理解
。如果屬性設為使用
ObjectDisplayOptions,
這個標籤會顯示在 屬性前面如果屬性已設定
,且 displayLabel
並未定義,只有屬性值
高度。
下列程式碼片段顯示具有 displayLabel
的 movieTitle
屬性
設定為「Title」。
{
"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 發出 UpdateSchema 要求註冊結構定義
詳見 UpdateSchema 參考頁面 發出以下 HTTP 要求以註冊您的結構定義:
PUT https://cloudsearch.googleapis.com/v1/indexing/{name=datasources/*}/schema
要求的內文應包含下列項目:
{ "validateOnly": // true or false, "schema": { // ... Your complete schema object ... } }
使用 validateOnly
選項測試結構定義是否有效
實際註冊該物件
建立資料索引
登錄結構定義後,請使用 索引 呼叫。系統通常會在內容連接器中建立索引。
使用電影結構定義時,如果對單一電影提出 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
的子資源 (因為是
透過使用 datePropertyOptions
來定義資料類型,藉此定義為 date
資料類型。
不過,由於結構定義中並未定義 year
、month
和 day
,因此
無法查詢其中一個屬性 (例如year
)。
另請注意,使用清單將可重複屬性 actorName
編入索引的方式
值。
找出潛在的索引問題
與結構定義和索引相關的兩個最常見的問題如下:
您的索引要求含有以下結構定義物件或屬性名稱: 已向結構定義服務註冊。這個問題會導致屬性或物件 。
索引要求的屬性類型值與類型不同 已登錄於結構定義中這個問題會導致 Cloud Search 傳回錯誤 在建立索引期間。
使用多種查詢類型測試結構定義
為大型實際工作環境資料存放區註冊結構定義之前, 建議您使用較小的測試資料存放區進行測試使用 可讓您快速調整結構定義 並刪除已建立索引的資料,而不會影響 或現有的實際工作環境索引如果是測試資料存放區,請建立 可授權給測試使用者的 ACL,方便其他使用者查看這項資料 。
如要建立搜尋介面來驗證搜尋查詢,請參閱 搜尋介面
這一節包含幾個可用來測試 電影結構定義
使用一般查詢進行測試
一般查詢會傳回資料來源中包含某個 字串。您可以利用搜尋介面,針對電影執行一般查詢 輸入「titanic」這個字詞,然後按 Return 鍵,來選取資料來源。所有語言 搭配「titanic」字樣的電影。
使用運算子進行測試
在查詢中加入運算子,即可將結果限制在相符的項目內
運算子的值。舉例來說,您可以使用 actor
運算子找出
由特定演員主演的所有電影。使用搜尋介面時,您可以執行下列操作:
這個運算子查詢只要輸入 operator=value 組合就能查詢,例如
「actor:Zane」"actor:Zane",然後按下 "actor:Zane" 鍵。所有與 Zane 相同的演員主角的電影
。
調整結構定義
使用結構定義和資料後,請繼續監控成效良好的元素 導致使用者無從使用發生下列情況時,建議您調整結構定義:
- 為先前未建立索引的欄位建立索引。舉例來說,您的使用者 可能會重複根據導演名稱搜尋電影,因此您 調整結構定義,以運算子形式支援董事名稱。
- 根據使用者意見變更搜尋運算子名稱。運算子名稱包括 是為了便於操作如果使用者持續「記住」錯 業者名稱,不妨考慮變更名稱。
結構定義變更後重新建立索引
如要在結構定義中變更下列任一值,則不需要 重新建立索引。您可以直接提交一份新的 UpdateSchema ,您的索引也會繼續運作:
- 運算子名稱。
- 整數的最小值和最大值。
- 整數和列舉排序排名。
- 時效性選項。
- 顯示選項。
在下列變更中,先前已建立索引的資料仍將持續運作 按照先前註冊的結構定義進行預測不過,您必須將 現有項目,然後根據更新後的結構定義查看變更 (若含有這些條件) 變更:
- 新增或移除新屬性或物件
- 將
isReturnable
、isFacetable
或isSortable
從false
變更為true
。
只有在有isFacetable
isSortable
true
明確用途和需求
最後,當您標記屬性 isSuggestable
來更新結構定義時,
您必須先為資料重新建立索引,導致系統延遲
該屬性。
不允許的資源變更
即使您為資料重新建立索引,也不得變更部分結構定義變更,因為 會破壞索引,或是產生不良或不一致的搜尋結果。這些 包括變更:
- 屬性資料類型。
- 屬性名稱。
- 「
exactMatchWithOperator
」設定。 - 「
retrievalImportance
」設定。
不過,有一個方法可以規避這項限制。
進行複雜的結構定義變更
避免進行變更,導致搜尋結果不佳或搜尋失效 Cloud Search 會在索引中防止某些類型的變更 UpdateSchema 要求。例如資料類型 屬性名稱在設定後即無法變更。這些變更 無法藉由 UpdateSchema 。
在必須採用其他不允許的情況下, 結構定義,通常您可以進行一系列「允許」變更,而這些變更都能達到相同的 效果。一般來說,這包括先遷移已建立索引的屬性 參照較新的物件定義,然後再傳送 僅使用較新屬性的索引要求。
下列步驟說明如何變更屬性的資料類型或名稱:
- 在結構定義中的物件定義新增屬性。改用其他裝置 命名屬性。
- 發出 UpdateSchema 重新定義要求。請記得傳送整個結構定義,包括
從資料存放區補充索引。如要補充索引,請將 使用新屬性 (但「非」 否則會導致重複計算查詢相符項目。
- 在建立索引的補充作業期間,請檢查新資源並 預設為舊的屬性,以免發生不一致的行為。
- 補充作業完成後,請執行測試查詢進行驗證。
刪除舊資源。核發其他問題 UpdateSchema ,並停止使用舊屬性, 名稱。
將所有使用舊資源遷移至新資源。舉例來說 如果您將屬性名稱從建立者變更為作者,就必須更新查詢 程式碼中,在先前提及創作者的位置使用作者。
Cloud Search 會將任何已刪除屬性或物件的記錄保留 30 天 ,避免因重複使用會導致索引意外結果的情形。 請在 30 天內,避免使用已刪除的項目 物件或屬性,包括從日後的索引要求省略。 這樣一來,如果您日後決定重新啟用該資源, 物件,藉由維護索引的正確性即可。
瞭解大小限制
Cloud Search 對結構化資料物件和結構定義的大小設有限制。 這些限制包括:
- 頂層物件最多只能有 10 個物件。
- 結構化資料階層的深度上限為 10 層。
- 物件中的欄位總數上限為 1000 個 其中包括原始欄位數量加上 每個巢狀物件中的 Field 欄位
後續步驟
以下是您可能採取的後續步驟:
建立搜尋介面,即可 測試結構定義
調整結構定義以提升搜尋品質。
瞭解如何運用 要定義的
_dictionaryEntry
結構定義 貴公司常用字詞的同義詞。如要使用_dictionaryEntry
結構定義,參照 定義同義詞。建立連接器。