Google Cloud Search 結構定義是一種 JSON 結構,用於定義用於建立資料索引及查詢資料的物件、屬性和選項。內容連接器會從存放區讀取資料,並根據已註冊的結構定義、結構並建立索引的資料。
您可以將 JSON 結構定義物件提供給 API,然後註冊以建立結構定義。您必須先為每個存放區註冊結構定義物件,才能為資料建立索引。
本文說明建立結構定義的基本概念。如要瞭解如何調整結構定義以改善搜尋體驗,請參閱「改善搜尋品質」。
建立結構定義
以下為建立 Cloud Search 結構定義的步驟清單:
識別預期的使用者行為
預測使用者提出的查詢類型有助於引導您制定結構定義的策略。
例如,對電影資料庫發出查詢時,您可能會預期使用者的查詢,例如「顯示有羅伯特瑞福主演的所有電影」。因此,您的結構定義必須支援以「特定演員的所有電影」查詢結果。
如要定義結構定義來反映使用者的行為模式,請考慮執行下列工作:
- 評估不同使用者想要的多元查詢組合。
- 找出可能用於查詢的物件。「物件」是相關資料的邏輯集,例如電影資料庫中的電影。
- 識別組成物件且可在查詢中使用的屬性和值。「屬性」是物件的可建立索引屬性,可包含原始值或其他物件。例如,電影物件可能具有電影名和發行日期等屬性做為原始值。電影物件也可能包含具有專屬屬性 (例如名稱或角色) 的其他物件 (例如演員)。
- 識別屬性的有效值範例。「值」是針對特定屬性建立索引的實際資料。舉例來說,資料庫中某部電影的標題可能是「失落方舟的突襲者」。
- 決定使用者所需的排序和排序選項。舉例來說,查詢電影時,使用者可能會想按時間順序排序並按目標對象評分進行排名,因此不需要按標題的字母順序排序。
- (選用) 請考慮其中一個屬性是否代表執行搜尋的具體情境,例如使用者的工作角色或部門,讓系統根據情境提供自動完成建議。例如,搜尋電影資料庫的使用者可能只對特定類型的電影感興趣。使用者可以定義想要搜尋的類型,也可做為使用者個人資料的一部分。這樣一來,當使用者開始查詢電影時,系統只會建議該類電影,例如「動作電影」做為自動完成建議的一部分。
- 列出可用於搜尋中的物件、屬性和範例值。(如要進一步瞭解這份清單的使用方式,請參閱「定義運算子選項」一節)。
初始化資料來源
「資料來源」則代表存放區已建立索引並儲存在 Google Cloud 中的資料。如需初始化資料來源的操作說明,請參閱管理第三方資料來源。
使用者的搜尋結果會從資料來源傳回。當使用者點選搜尋結果時,Cloud Search 會使用索引要求中提供的網址,將使用者導向實際的項目。
定義物件
結構定義中的資料基本單位是「物件」,也稱為「結構定義物件」,這是資料的邏輯結構。在電影資料庫中,一種資料邏輯結構是「電影」。另一個物件可能是代表電影中的演員和工作人員。
結構定義中的每個物件都有一系列的屬性或描述該物件的屬性,例如電影的標題與持續時間,或是某人的姓名和出生日期。物件的屬性可包含原始值或其他物件。
圖 1 顯示電影和人物物件及相關聯的屬性。
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
物件中,又在 person
物件的 filmography
子物件中再次定義一次。這個結構定義會重複使用 movieTitle
欄位,因此結構定義可以支援兩種搜尋行為:
- 當使用者搜尋電影標題時,顯示電影搜尋結果。
- 當使用者搜尋演員播放的電影標題時,顯示人物搜尋結果。
同樣地,結構定義會重複使用 releaseDate
欄位,因為該欄位對兩個 movieTitle
欄位的影響相同。
在開發自己的結構定義時,請考慮存放區中有哪些相關欄位,其中包含您希望在結構定義中宣告多次的資料。
新增不限類型選項
PropertyDefinition 列出所有屬性通用的一般搜尋功能選項,無論資料類型為何。
isReturnable
:表示屬性是否識別應透過 Query API 在搜尋結果中傳回的資料。所有範例電影屬性都可供傳回。非可傳回的屬性可用於搜尋或排名結果,而不必傳回使用者。isRepeatable
- 表示屬性是否允許多個值。舉例來說,一部電影只有一個發行日期,但可以有多位演員。isSortable
:代表屬性可用於排序。如果是可重複的屬性,則並非如此。例如,可按照發行日期或觀眾評分來排序電影的搜尋結果。isFacetable
:代表屬性可用來產生「商情項目」facets。Facet 可用於修正搜尋結果,使用者看到初始結果後,即可新增條件或商情項目,進一步縮小結果範圍。如果屬性類型為物件,則isReturnable
必須為 true 才能設定此選項。最後,這個選項僅支援列舉、布林值和文字屬性。例如,在我們的範例結構定義中,我們可能會製作genre
、actorName
、userRating
和mpaaRating
商情項目,以便用於互動式縮小搜尋結果範圍。isWildcardSearchable
表示使用者可以針對這個屬性執行萬用字元搜尋。這個選項僅適用於文字屬性。萬用字元搜尋的運作方式,取決於文字欄位在 exactMatchWithOperator 欄位中設定的值。如果將exactMatchWithOperator
設為true
,系統就會將文字值代碼化為一個原子值,並針對該值執行萬用字元搜尋。舉例來說,如果文字值為science-fiction
,萬用字元查詢science-*
就會與該查詢相符。如果exactMatchWithOperator
設為false
,文字值就會權杖化,並對每個符記執行萬用字元搜尋。舉例來說,如果文字值為「science-science」,萬用字元查詢sci*
或fi*
會與該項目相符,但science-*
則不相符。
這些一般搜尋功能參數都是布林值;這些參數都有預設值 false
,必須設為 true
才能使用。
下表顯示 movie
物件所有屬性的布林值參數,設為 true
:
屬性 | 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
,表示電影標題屬於類型文字。下列程式碼片段顯示擁有 textPropertyOptions
設定資料類型的 movieTitle
屬性。
{
"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
是日期物件。舉例來說,假如預期用途是比較多年版本與 1 月的版本,則字串格式可能很實用。
設定類型專屬選項
PropertyDefinition 參考資料部分連結至各個類型的選項。除了 enumPropertyOptions
中的 possibleValues
清單以外,大多數類型的特定選項都是選用選項。此外,orderedRanking
選項可讓您為值之間的相對排名。以下程式碼片段顯示含有 textPropertyOptions
設定資料類型和 retrievalImportance
類型專屬選項的 movieTitle
屬性。
{
"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
這些選項,描述屬性做為搜尋運算子的使用方式。以下程式碼片段顯示含有 textPropertyOptions
設定資料類型的 movieTitle
屬性,以及 retrievalImportance
和 operatorOptions
類型專屬選項。
{
"name": "movieTitle",
"isReturnable": true,
"isWildcardSearchable": true,
"textPropertyOptions": {
"retrievalImportance": { "importance": "HIGHEST" },
"operatorOptions": {
"operatorName": "title"
}
},
...
}
每個 operatorOptions
都有 operatorName
,例如適用於 movieTitle
的 title
。運算子名稱是屬性的搜尋運算子。搜尋運算子是使用者縮小搜尋範圍時,您預期會使用的實際參數。舉例來說,如要根據片名搜尋電影,使用者會輸入 title:movieName
,其中 movieName
是電影名稱。
運算子名稱不一定要與屬性名稱相同。相反地,您應該使用能反映貴機構使用者最常用字詞的運算子名稱。舉例來說,如果使用者偏好使用「name」這個字詞而非「title」來提交電影名稱,則運算子名稱應設為「name」。
只要所有屬性都解析為相同類型,就可以為多個屬性使用相同的運算子名稱。在查詢期間使用共用運算子名稱時,系統會擷取使用該運算子名稱的所有屬性。舉例來說,假設電影物件具有 plotSummary
和 plotSynopsis
屬性,且每個屬性都有 plot
的 operatorName
。只要這兩個屬性都是文字 (textPropertyOptions
),使用 plot
搜尋運算子的單一查詢就能同時擷取這兩個屬性。
除了 operatorName
之外,可排序的屬性在 operatorOptions
中也可包含 lessThanOperatorName
和 greaterThanOperatorName
欄位。使用者可以使用這些選項,根據與提交值的比較來建立查詢。
最後,textOperatorOptions
的 operatorOptions
中有一個 exactMatchWithOperator
欄位。如果您將 exactMatchWithOperator
設為 true
,查詢字串必須與整個屬性值相符,而不能只是文字內。在運算子搜尋和 Facet 比對中,文字值會視為一個不可分割的值。
舉例來說,請考慮為含有類型屬性的書籍或電影物件建立索引。類型包括「科學 - 小說」、「科學」和「Fiction」。如果將 exactMatchWithOperator
設為 false
或省略,搜尋類型或選取「科學」或「Fiction」商情項目也會傳回「Science-Fiction」 (代碼化文字) 的結果,且「Science-Fiction」會有「Science-Fiction」符記。當 exactMatchWithOperator
為 true
時,系統會將文字視為單一符記,因此「Science」和「Fiction」都不會與「Science-Fiction」相符。
(選用) 新增 displayOptions
區段
任何 propertyDefinition
區段的結尾都有一個選用的 displayOptions
部分。這個區段包含一個 displayLabel
字串。displayLabel
是建議且容易理解的屬性文字標籤。如果使用 ObjectDisplayOptions 將屬性設定為顯示,此標籤會顯示在屬性前方。如果已設定顯示屬性,且未定義 displayLabel
,則只會顯示屬性值。
下列程式碼片段是 movieTitle
屬性,displayLabel
設為「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[]
」版面
propertyDefinition
部分結尾處有一個選用的 suggestionFilteringOperators[]
部分。請在這個部分定義用於篩選自動完成建議的屬性。舉例來說,您可以定義 genre
運算子,根據使用者偏好的電影類型篩選建議。之後,當使用者輸入搜尋查詢時,自動完成建議中只會顯示符合他們偏好的電影類型。
註冊結構定義
如要使 Cloud Search 查詢傳回結構化資料,您必須向 Cloud Search 結構定義服務註冊結構定義。註冊結構定義需要您在初始化資料來源步驟中取得的資料來源 ID。
使用資料來源 ID 發出 UpdateSchema 要求來註冊結構定義。
如 UpdateSchema 參考資料頁面所述,請發出以下 HTTP 要求來註冊結構定義:
PUT https://cloudsearch.googleapis.com/v1/indexing/{name=datasources/*}/schema
要求內文應包含以下內容:
{ "validateOnly": // true or false, "schema": { // ... Your complete schema object ... } }
在不實際註冊結構定義的情況下,使用 validateOnly
選項即可測試結構定義是否有效。
為資料建立索引
登錄結構定義後,請使用 Index 呼叫填入資料來源。索引通常會在內容連接器中完成。
使用電影結構定義時,單一電影的 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") 並按下 Return 鍵,即可執行這項運算子查詢。凡是以 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 個,其中包含原始欄位數量加上每個巢狀物件中的欄位數量總和。
後續步驟
以下是您可以採取的後續步驟:
建立搜尋介面來測試結構定義。
調整結構定義以提升搜尋品質。
瞭解如何利用
_dictionaryEntry
結構定義,為貴公司常用的字詞定義同義詞。如要使用_dictionaryEntry
結構定義,請參閱定義同義詞。建立連接器。