Google Cloud Search 結構定義是一種 JSON 結構,可以定義用於建立索引及查詢資料的物件、屬性和選項。內容連接器會根據您註冊的結構定義、結構及索引,從存放區讀取資料。
如要建立結構定義,您可以提供 JSON 結構定義物件給 API,然後進行註冊。您必須先為每個存放區註冊結構定義物件,才能為資料建立索引。
本文說明結構定義建立機制的基本概念。如要瞭解如何調整結構定義來改善搜尋體驗,請參閱「改善搜尋品質」。
建立結構定義
以下是建立 Cloud Search 結構定義的步驟清單:
找出預期的使用者行為
預測使用者的查詢類型有助於引導建立結構定義的策略。
舉例來說,對電影資料庫發出查詢時,您可能會預期使用者的查詢內容,例如「Show me all movies starring Robert Redford」(顯示由小羅主演的所有電影)。因此,您的結構定義必須支援以「具有特定演員的所有電影」為依據的查詢結果。
如要定義結構定義來反映使用者的行為模式,請考慮執行下列工作:
- 評估不同使用者所做的各種查詢。
- 識別可能在查詢中使用的物件。物件是相關資料的邏輯集,例如電影資料庫中的電影。
- 識別組成物件且可能用於查詢的屬性與值。屬性是物件的可建立索引屬性,且可包含原始值或其他物件。舉例來說,電影物件可具有做為原始值的屬性,像是電影標題和發行日期。電影物件也可能包含其他具有專屬屬性的物件 (例如層級轉換成員),這些物件具有各自的名稱或角色。
- 找出屬性的有效值範例。「值」是屬性建立索引的實際資料。例如,資料庫中一部電影的片名可能是「失落的方舟」;
- 決定使用者所需的排序與排名選項。舉例來說,查詢電影時,使用者可能會想按時間順序排序並依目標對象評分排序,因此不需依標題的字母順序排序。
- (選用) 請思考某個屬性是否代表執行搜尋的更具體情境 (例如使用者的角色或部門),以便系統根據情境提供自動完成建議。舉例來說,如果使用者搜尋電影資料庫,可能只會對特定類型的電影感興趣。使用者會定義想要傳回的搜尋類型,可能包含在使用者個人資料中。這樣一來,當使用者開始輸入電影查詢時,系統只會建議屬於其偏好的類型 (例如「動作片」) 做為自動完成建議。
- 列出可用於搜尋的物件、屬性和範例值的清單。(如要進一步瞭解這份清單的使用方式,請參閱「定義運算子選項」一節)。
初始化資料來源
「資料來源」代表存放區中的資料,且該存放區已建立索引並儲存在 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
物件的 filmography
子物件中一次,而在 person
物件的 filmography
子物件中又定義一次。這個結構定義會重複使用 movieTitle
欄位,因此結構定義可以支援兩種類型的搜尋行為:
- 使用者搜尋電影標題時,顯示電影搜尋結果。
- 當使用者搜尋某位演員所播電影的名稱時,顯示人物結果。
同樣地,結構定義會重複使用 releaseDate
欄位,因為這個欄位對兩個 movieTitle
欄位的定義相同。
開發自己的結構定義時,請考慮存放區的相關欄位,包含您在結構定義中多次宣告的資料。
新增類型通用選項
PropertyDefinition 會列出所有屬性通用的一般搜尋功能選項,無論資料類型為何。
isReturnable
:表示屬性是否指明應透過 Query API 在搜尋結果中傳回的資料。所有範例電影屬性都可以傳回。無法傳回的屬性可用於搜尋或排名結果,而不必傳回使用者。isRepeatable
- 表示屬性是否允許多個值。舉例來說,一部電影只有一個發行日期,但可以有多個演員。isSortable
- 表示屬性可用於排序。如果是可重複的屬性,則無效。舉例來說,電影搜尋結果可依照播映日期或觀眾分級排序。isFacetable
- 表示屬性可用於產生「facet」facets。使用者可在看到初始結果後新增條件或 facet,藉此修正搜尋結果。如果屬性的類型為物件,且isReturnable
必須為 true,則這個選項不得為 true。最後,這個選項僅適用於列舉、布林值和文字屬性。例如,在範例結構定義中,我們可能會建立genre
、actorName
、userRating
和mpaaRating
facetable,以便用於互動式修正搜尋結果。isWildcardSearchable
表示使用者可以對這個屬性執行萬用字元搜尋。這個選項僅適用於文字屬性。萬用字元搜尋在文字欄位中的運作方式,取決於 exactMatchWithOperator 欄位設定的值。如果將exactMatchWithOperator
設為true
,系統會將文字值代碼化為一個不可拆分的值,並對其執行萬用字元搜尋。舉例來說,如果文字值是science-fiction
,則萬用字元查詢science-*
與這個值相符。如果將exactMatchWithOperator
設為false
,系統就會為文字值代碼化,並對每個符記執行萬用字元搜尋。舉例來說,如果文字值是「science-cpm」,萬用字元查詢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
是日期物件。舉例來說,如果比較年分 12 月版本與 1 月版本的用途是預期的用途,那麼字串格式或許就很實用。
設定類型專屬的選項
PropertyDefinition 參考資料部分提供各類型選項的連結。除了 enumPropertyOptions
中的 possibleValues
清單以外,大多數類型專用的選項皆為選用選項。此外,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
。這些選項說明如何將屬性做為搜尋運算子使用。下列程式碼片段顯示具有 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 比對中,文字值會視為一個不可分割的值。
舉例來說,請考慮為含有類型屬性的「圖書」或「電影」物件建立索引。類型可能包含「科學」、「科學」和「小說」。如果 exactMatchWithOperator
設為 false
或省略,則搜尋類型或選取「科學」或「小說」 facet 時,也會傳回「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 層。
- 物件中的欄位總數上限為 1,000 個,其中包括原始欄位數量,再加上每個巢狀物件中的欄位數量總和。
後續步驟
以下是您可能採取的後續步驟:
建立搜尋介面來測試結構定義。
調整結構定義以提升搜尋品質。
瞭解如何利用
_dictionaryEntry
結構定義,定義公司常用字詞的同義詞。如要使用_dictionaryEntry
結構定義,請參閱定義同義詞。建立連接器。