本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 Gremlin `mergeV()` 和 `mergeE()` 步驟進行有效的 upsert
upsert (或條件式插入) 會重複使用頂點或邊緣 (如果它已經存在)，或者如果不存在，則建立它。有效的 upsert 可以在 Gremlin 查詢的效能上產生顯著的差異。
Upsert 可讓您撰寫等冪性插入操作：無論您執行多少次這類操作，整體結果都是一樣的。這在高度並行寫入案例中非常有用，其中對圖形的相同部分進行並行修改可以強制一或多個交易使用 `ConcurrentModificationException` 進行復原，從而需要重試。
例如，以下查詢會使用提供的 `Map` upsert 頂點，以首先嘗試尋找 `T.id` 為 `"v-1"` 的頂點。如果找到該頂點，則會傳回它。如果沒有找到，則會透過 `onCreate` 子句建立具有該 `id` 和屬性的頂點。
```
g.mergeV([(id):'v-1']).
option(onCreate, [(label): 'PERSON', 'email': 'person-1@example.org'])
```
## 批次 upsert 以改善輸送量
對於高輸送量寫入案例，您可以將 `mergeV()` 和 `mergeE()` 步驟鏈結在一起，以批次方式 upsert 頂點和邊緣。批次處理可減少 upsert 大量頂點和邊緣的交易負荷。然後，您可以使用多個用戶端平行 upsert 批次請求，進一步改善輸送量。
根據經驗法則，我們建議每個批次請求 upsert 大約 200 筆記錄。記錄是單一頂點或邊緣標籤或屬性。例如，具有單一標籤和 4 個屬性的頂點會建立 5 筆記錄。具有一個標籤和單一屬性的邊緣會建立 2 筆記錄。如果您想要 upsert 頂點批次，每個頂點都有單一標籤和 4 個屬性，您應該從 40 的批次大小開始，因為 `200 / (1 + 4) = 40`。
您可以嘗試批次大小。每個批次 200 筆記錄是一個很好的起點，但理想的批次大小可能會更高或更低，取決於您的工作負載。不過，請注意，Neptune 可能會限制每個請求的 Girmlin 步驟總數。此限制沒有明文記載，但為了安全起見，請嘗試確保您的請求包含不超過 1,500 個 Gemlin 步驟。Neptune 可能會拒絕超過 1,500 個步驟的大型批次請求。
若要增加輸送量，您可以使用多個用戶端平行 upsert 批次 (請參閱 [建立有效率的多執行緒 Gremlin 寫入](best-practices-gremlin-multithreaded-writes.md))。用戶端數目應與 Neptune 寫入器執行個體上的工作者執行緒數目相同，通常是伺服器上 vCPU 數目的 2 倍。例如，一個 `r5.8xlarge` 執行個體具有 32 個 vCPU 和 64 個工作者執行緒。對於使用 `r5.8xlarge` 的高輸送量寫入案例，您將會使用 64 個將批次 upsert 平行寫入 Neptune 的用戶端。
每個用戶端都應提交批次請求，並等待請求完成，然後再提交另一個請求。儘管多個用戶端平行執行，但每個個別的用戶端以都序列方式提交請求。這可確保為伺服器提供穩定的請求串流，這些請求會佔用所有工作者執行緒，而不會大量湧入伺服器端要求佇列 (請參閱 [調整 Neptune 資料庫叢集中資料庫執行個體的大小](feature-overview-db-clusters.md#feature-overview-sizing-instances))。
## 嘗試避免產生多個周遊器的步驟
當一個 Gemlin 步驟執行時，它需要一個傳入的周遊器，並發出一個或多個輸出周遊器。由一個步驟發出的周遊器數目會確定下一個步驟的執行次數。
通常，在執行批次操作時，您想要每個操作 (例如 upsert 頂點 A) 執行一次，以便操作序列看起來像這樣：upsert 頂點 A、接著 upsert 頂點 B，然後 upsert 頂點 C，依此類推。只要一個步驟僅建立或修改一個元素，它就只會發出一個周遊器，而代表下一個操作的步驟只會執行一次。另一方面，如果一個操作建立或修改多個元素，它會發出多個周遊器，這又會導致後續步驟執行多次，每個發出的周遊器一次。這可能會導致資料庫執行不必要的額外工作，並且在某些情況下可能會導致建立不需要的其他頂點、邊緣或屬性值。
一個可能出錯的範例是類似 `g.V().addV()` 的查詢。這個簡單的查詢會為圖形中找到的每個頂點新增一個頂點，因為 `V()` 會為圖形中的每個頂點發出一個周遊器，而且其中每個周遊器都會觸發對 `addV()` 的呼叫。
如需處理可以發出多個周遊器之操作的方法，請參閱 [混合 upsert 和插入](#gremlin-upserts-and-inserts)。
## Upsert 頂點
`mergeV()` 步驟是專門針對 upsert 頂點而設計的。它會以引數形式採取 `Map`，其代表要針對圖形中現有頂點進行比對的元素，而且如果找不到一個元素，則會使用該 `Map` 建立一個新的頂點。此步驟還可讓您在建立或比對的情況下變更行為，其中 `option()` 調幅器可與 `Merge.onCreate` 和 `Merge.onMatch` 權杖一起套用，來控制這些各自的行為。如需有關如何使用此步驟的進一步資訊，請參閱 TinkerPop [參考文件](https://tinkerpop.apache.org/docs/current/reference/#mergevertex-step)。
您可以使用頂點 ID 來判斷特定頂點是否存在。這是偏好的方法，因為 Neptune 會針對 ID 周圍的高度並行使用案例最佳化 upsert。舉例來說，以下查詢會建立具有給定頂點 ID 的頂點 (如果尚未存在)，或重複使用它 (如果存在)：
```
g.mergeV([(T.id): 'v-1']).
option(onCreate, [(T.label): 'PERSON', email: 'person-1@example.org', age: 21]).
option(onMatch, [age: 22]).
id()
```
請注意，此查詢以 `id()` 步驟結尾。雖然基於 upsert 頂點的目的並不是絕對必要的，但 upsert 查詢結尾的 `id()` 步驟可確保伺服器不會將所有頂點屬性序列化回用戶端，這有助於降低查詢的鎖定成本。
或者，您可以使用頂點屬性來識別頂點：
```
g.mergeV([email: 'person-1@example.org']).
option(onCreate, [(T.label): 'PERSON', age: 21]).
option(onMatch, [age: 22]).
id()
```
如果可能的話，請使用您自己使用者提供的 ID 來建立頂點，並使用這些 ID 來判斷在 upsert 操作期間頂點是否存在。這可讓 Neptune 最佳化 upsert。當並行修改很常見時，ID 型 upsert 可能明顯比屬性型 upsert 更有效率。
### 鏈結頂點 upsert
您可以將頂點 upsert 鏈結在一起，以批次方式插入它們：
```
g.V('v-1')
.fold()
.coalesce(unfold(),
addV('Person').property(id, 'v-1')
.property('email', 'person-1@example.org'))
.V('v-2')
.fold()
.coalesce(unfold(),
addV('Person').property(id, 'v-2')
.property('email', 'person-2@example.org'))
.V('v-3')
.fold()
.coalesce(unfold(),
addV('Person').property(id, 'v-3')
.property('email', 'person-3@example.org'))
.id()
```
或者，您也可以使用下列 `mergeV()` 語法：
```
g.mergeV([(T.id): 'v-1', (T.label): 'PERSON', email: 'person-1@example.org']).
mergeV([(T.id): 'v-2', (T.label): 'PERSON', email: 'person-2@example.org']).
mergeV([(T.id): 'v-3', (T.label): 'PERSON', email: 'person-3@example.org'])
```
不過，因為這種形式的查詢包含了搜尋條件中對於基本查詢 (依 `id`) 而言是多餘的元素，所以效率不如先前的查詢。
## Upsert 邊緣
`mergeE()` 步驟是專門針對 upsert 邊緣而設計的。它會以引數形式採取 `Map`，其代表要針對圖形中現有邊緣進行比對的元素，而且如果找不到一個元素，則會使用該 `Map` 建立一個新的邊緣。此步驟還可讓您在建立或比對的情況下變更行為，其中 `option()` 調幅器可與 `Merge.onCreate` 和 `Merge.onMatch` 權杖一起套用，來控制這些各自的行為。如需有關如何使用此步驟的進一步資訊，請參閱 TinkerPop [參考文件](https://tinkerpop.apache.org/docs/current/reference/#mergeedge-step)。
您可以使用邊緣 ID，以與您使用自訂頂點 ID upsert 頂點的相同方式來 upsert 邊緣。同樣地，這是偏好的方法，因為它允許 Neptune 最佳化查詢。例如，以下查詢會根據邊緣 ID 建立邊緣 (如果不存在)，或者如果存在，則會重複使用它。如果此查詢需要建立一個新的邊緣，它也會使用 `Direction.from` 和 `Direction.to` 頂點的 ID：
```
g.mergeE([(T.id): 'e-1']).
option(onCreate, [(from): 'v-1', (to): 'v-2', weight: 1.0]).
option(onMatch, [weight: 0.5]).
id()
```
請注意，此查詢以 `id()` 步驟結尾。雖然基於 upsert 邊緣的目的並不是絕對必要的，但將 `id()` 步驟新增至查詢結尾可確保伺服器不會將所有邊緣屬性序列化回用戶端，這有助於降低查詢的鎖定成本。
許多應用程式會使用自訂頂點 ID，但會讓 Neptune 產生邊緣 ID。如果您不知道邊緣的 ID，但確實知道 `from` 和 `to` 頂點 ID，則可以使用這種查詢來 upsert 邊緣：
```
g.mergeE([(from): 'v-1', (to): 'v-2', (T.label): 'KNOWS']).
id()
```
`mergeE()` 參考的所有頂點都必須存在，步驟才能建立邊緣。
### 鏈結邊緣 upsert
與頂點 upsert 一樣，將批次請求的 `mergeE()` 步驟鏈結在一起很簡單：
```
g.mergeE([(from): 'v-1', (to): 'v-2', (T.label): 'KNOWS']).
mergeE([(from): 'v-2', (to): 'v-3', (T.label): 'KNOWS']).
mergeE([(from): 'v-3', (to): 'v-4', (T.label): 'KNOWS']).
id()
```
## 結合頂點和邊緣 upsert
有時您可能想要 upsert 頂點和連線它們的邊緣。您可以混合此處呈現的批次範例。以下範例會 upsert 3 個頂點和 2 個邊緣：
```
g.mergeV([(id):'v-1']).
option(onCreate, [(label): 'PERSON', 'email': 'person-1@example.org']).
mergeV([(id):'v-2']).
option(onCreate, [(label): 'PERSON', 'email': 'person-2@example.org']).
mergeV([(id):'v-3']).
option(onCreate, [(label): 'PERSON', 'email': 'person-3@example.org']).
mergeE([(from): 'v-1', (to): 'v-2', (T.label): 'KNOWS']).
mergeE([(from): 'v-2', (to): 'v-3', (T.label): 'KNOWS']).
id()
```
## 混合 upsert 和插入
有時您可能想要 upsert 頂點和連線它們的邊緣。您可以混合此處呈現的批次範例。以下範例會 upsert 3 個頂點和 2 個邊緣：
Upsert 通常一次處理一個元素。如果您堅持使用此處呈現的 upsert 模式，則每個 upsert 操作都會發出單一周遊器，這會導致後續操作僅執行一次。
不過，有時您可能想要混合 upsert 與插入。例如，如果您使用邊緣來代表動作或事件的執行個體，則可能會發生這種情況。請求可能會使用 upsert 來確保所有必要的頂點都存在，然後使用插入來新增邊緣。對於這種請求，請注意從每個操作發出的潛在周遊器數目。
考慮以下範例，它混合了 upsert 和插入，以將代表事件的邊緣新增至圖形：
```
// Fully optimized, but inserts too many edges
g.mergeV([(id):'v-1']).
option(onCreate, [(label): 'PERSON', 'email': 'person-1@example.org']).
mergeV([(id):'v-2']).
option(onCreate, [(label): 'PERSON', 'email': 'person-2@example.org']).
mergeV([(id):'v-3']).
option(onCreate, [(label): 'PERSON', 'email': 'person-3@example.org']).
mergeV([(T.id): 'c-1', (T.label): 'CITY', name: 'city-1']).
V('p-1', 'p-2').
addE('FOLLOWED').to(V('p-1')).
V('p-1', 'p-2', 'p-3').
addE('VISITED').to(V('c-1')).
id()
```
查詢應該插入 5 個邊緣：2 FOLLOWED 邊緣和 3 VISITED 邊緣。不過，查詢在撰寫時會插入 8 個邊緣：2 個 FOLLOWED 和 6 個 VISITED。這樣做的原因是，插入 2 個 FOLLOWED 邊緣的操作會發出 2 個周遊器，從而導致後續的插入操作 (插入 3 個邊緣) 執行兩次。
修正方法是在每個可能發出多個周遊器的操作之後新增一個 `fold()` 步驟：
```
g.mergeV([(T.id): 'v-1', (T.label): 'PERSON', email: 'person-1@example.org']).
mergeV([(T.id): 'v-2', (T.label): 'PERSON', email: 'person-2@example.org']).
mergeV([(T.id): 'v-3', (T.label): 'PERSON', email: 'person-3@example.org']).
mergeV([(T.id): 'c-1', (T.label): 'CITY', name: 'city-1']).
V('p-1', 'p-2').
addE('FOLLOWED').
to(V('p-1')).
fold().
V('p-1', 'p-2', 'p-3').
addE('VISITED').
to(V('c-1')).
id()
```
在這裡，我們已在插入 FOLLOWED 邊緣的操作後面插入 `fold()` 步驟。這會產生單一周遊器，然後導致後續操作僅執行一次。
這種方法的缺點是查詢現在未完全最佳化，因為 `fold()` 未最佳化。接在 `fold()` 後面的插入操作現在也不會最佳化。
如果您需要使用 `fold()`，代表後續步驟減少周遊器的數目，請嘗試排序您的操作，以便最便宜的操作佔用查詢的非最佳化部分。
## 設定基數
已設定 Neptune 中頂點屬性的預設基數，這表示在使用 mergeV() 時，地圖中提供的值都會被賦予該基數。若要使用單一基數，您必須明確說明其用量。從 TinkerPop 3.7.0 開始，有新的語法允許基數作為映射的一部分提供，如下列範例所示：
```
g.mergeV([(T.id): '1234']).
option(onMatch, ['age': single(20), 'name': single('alice'), 'city': set('miami')])
```
或者，您可以將基數設定為預設基數`option`，如下所示：
```
// age and name are set to single cardinality by default
g.mergeV([(T.id): '1234']).
option(onMatch, ['age': 22, 'name': 'alice', 'city': set('boston')], single)
```
在 3.7.0 版`mergeV()`之前的 中設定基數的選項較少。一般方法是返回`property()`步驟，如下所示：
```
g.mergeV([(T.id): '1234']).
option(onMatch, sideEffect(property(single,'age', 20).
property(set,'city','miami')).constant([:]))
```
**注意**
此方法只有在與啟動步驟搭配使用`mergeV()`時，才能使用 。因此，您無法在單一周遊`mergeV()`中鏈結，因為在使用此語法的開始步驟`mergeV()`之後的第一個步驟會在傳入周遊是圖形元素時產生錯誤。在這種情況下，您會想要將`mergeV()`呼叫分成多個請求，其中每個請求都可以是開始步驟。