エンティティ キーの作成と使用

Datastore 内の各エンティティは、キーによって一意に識別されます。キーは次のコンポーネントで構成されています。

  • エンティティの名前空間。マルチテナンシーを可能にします。
  • エンティティの種類。Datastore クエリ用にエンティティを分類します。
  • オプションの祖先パス。Datastore 階層内のエンティティの位置を指定します

  • 個々のエンティティの識別子。次のいずれかになります。

    • キー名の文字列
    • 整数の数値 ID

識別子はエンティティ キーの構成要素です。エンティティに永続的に割り当てられるため、変更できません。識別子は、次のいずれかの方法で割り当てます。

  • エンティティに固有のキー名文字列を指定する。
  • Datastore がエンティティに整数の数値 ID を自動的に割り当てる。

エンティティにキー名を指定する

エンティティにキー名を割り当てるには、空でない stringID 引数を datastore.NewKey に渡します。

// Create a key with a key name "asalieri".
key := datastore.NewKey(
	ctx,        // context.Context
	"Employee", // Kind
	"asalieri", // String ID; empty means no string ID
	0,          // Integer ID; if 0, generate automatically. Ignored if string ID specified.
	nil,        // Parent Key; nil means no parent
)

Datastore が数値 ID を自動的に割り当てるように設定するには、空の stringID 引数を使用します。

// Create a key such as Employee:8261.
key := datastore.NewKey(ctx, "Employee", "", 0, nil)
// This is equivalent:
key = datastore.NewIncompleteKey(ctx, "Employee", nil)

識別子の割り当て

2 つの異なる自動 ID ポリシーを使用して自動 ID を生成するように、Datastore を構成できます。

  • default ポリシーは、ほぼ均等に分布する未使用の ID をランダムに生成します。各 ID は最大 16 桁の 10 進数になります。
  • legacy ポリシーは、連続しない小さい整数の ID を作成します。

エンティティの ID をユーザーに表示する場合や、ID の順序に従ってなんらかの処理を行う場合は、手動で割り当てることをおすすめします。

祖先パスを使用する

Cloud Datastore 内のエンティティは、ファイル システムのディレクトリ構造と同様に、階層的に構造化された空間を形成します。エンティティを作成するときに、別のエンティティを親として設定することもできます。新しいエンティティは、この親エンティティの子になります（ファイル システムとは異なり、親エンティティが実際に存在している必要はありません）。親を持たないエンティティは「ルート エンティティ」となります。エンティティと親との割り当ては永続的であり、エンティティの作成後は変更できません。同じ親を持つ 2 つのエンティティ、または 2 つのルート エンティティ（親を持たないエンティティ）に同じ数値 ID が割り当てられることはありません。

エンティティの親、親の親、さらにその親などは順に「祖先」として位置付けられ、エンティティの子、子の子、さらにその子などは順に「子孫」として位置付けられます。ルート エンティティとその子孫のエンティティは、すべて同じエンティティ グループに属します。ルート エンティティから始まり、親から子を経由して対象のエンティティに至るまでのエンティティの連なりのことを、エンティティの「祖先パス」といいます。エンティティを識別する完全なキーは、エンティティの祖先パスから始まってそのエンティティ自身で終わる一連の「種類と識別子のペア」で構成されています。

[Person:GreatGrandpa, Person:Grandpa, Person:Dad, Person:Me]

ルート エンティティの場合は祖先パスが空で、エンティティ自身の種類と識別子だけでキーが構成されています。

[Person:GreatGrandpa]

このコンセプトを次の図に示します。

エンティティ グループ内のルート エンティティと子エンティティの関係を示す図

エンティティの親を指定するには、datastore.NewKey に対して parent 引数を使用します。この引数の値は、親エンティティのキーである必要があります。次の例では、種類が Address のエンティティを作成し、Employee エンティティを親として指定しています。

// Create Employee entity
employee := &Employee{ /* ... */ }
employeeKey, err := datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Employee", nil), employee)

// Use Employee as Address entity's parent
// and save Address entity to datastore
address := &Address{ /* ... */ }
addressKey := datastore.NewIncompleteKey(ctx, "Address", employeeKey)
_, err = datastore.Put(ctx, addressKey, address)