Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

エンティティ、プロパティ、キー

Datastore モードの Firestore では、データオブジェクトをエンティティといいます。エンティティは 1 つ以上の名前付きプロパティを持ち、各プロパティが 1 つ以上の値を持ちます。同じ種類のエンティティが同じプロパティを持つとは限りません。また、エンティティの特定のプロパティの値がすべて同じデータ型である必要はありません。（必要に応じて、アプリケーション独自のデータモデルでこのような制限を確立して強制できます）。

Datastore モードでは、プロパティ値でさまざまなデータ型がサポートされています。サポートしているデータ型の例を次に示します。

整数
浮動小数点数
文字列
日付
バイナリデータ

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

エンティティの名前空間。マルチテナンシーを可能にします
エンティティの種類。クエリ用にエンティティを分類します
個々のエンティティの識別子。次のいずれかになります
- キー名の文字列
- 整数の数値 ID
オプションの祖先パス。データベース階層内のエンティティの位置を指定します

アプリケーションはエンティティのキーを使用してデータベースから個々のエンティティを取得できます。また、エンティティのキーやプロパティ値に基づくクエリを発行して 1 つ以上のエンティティを取得することもできます。

Datastore モードの Firestore 自体がエンティティの構造になんらかの制限（特定のプロパティは特定の型の値を持たなければならないなど）を課すことはありません。この役割はアプリケーションが担います。

このページのスニペットは、Datastore モードの Firestore のスタートガイドの例に基づいています。

エンティティを操作する

アプリケーションは Datastore モードの Firestore API を使用して、エンティティの作成、取得、更新、削除を行うことができます。エンティティの完全なキーがわかっている場合（または親のキー、種類、識別子からキーを導出できる場合）、アプリケーションはそのキーを使用してエンティティを直接操作できます。また、クエリの結果としてエンティティのキーを取得することもできます。詳細については、クエリをご覧ください。

エンティティの作成

新しいエンティティを作成するには、エンティティを初期化してプロパティを設定します。

C#

Cloud Datastore 用のクライアントライブラリをインストールして使用する方法については、Cloud Datastore のクライアントライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンスドキュメントをご覧ください。

Cloud Datastore への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。

Entity task = new Entity()
{
    Key = _db.CreateKeyFactory("Task").CreateKey("sampleTask"),
    ["category"] = "Personal",
    ["done"] = false,
    ["priority"] = 4,
    ["description"] = "Learn Cloud Datastore"
};

Go

Cloud Datastore 用のクライアントライブラリをインストールして使用する方法については、Cloud Datastore のクライアントライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンスドキュメントをご覧ください。

type Task struct {
	Category        string
	Done            bool
	Priority        float64
	Description     string `datastore:",noindex"`
	PercentComplete float64
	Created         time.Time
}
task := &Task{
	Category:        "Personal",
	Done:            false,
	Priority:        4,
	Description:     "Learn Cloud Datastore",
	PercentComplete: 10.0,
	Created:         time.Now(),
}

Java

Cloud Datastore 用のクライアントライブラリをインストールして使用する方法については、Cloud Datastore のクライアントライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンスドキュメントをご覧ください。

Key taskKey = datastore.newKeyFactory().setKind("Task").newKey("sampleTask");
Entity task =
    Entity.newBuilder(taskKey)
        .set("category", "Personal")
        .set("done", false)
        .set("priority", 4)
        .set("description", "Learn Cloud Datastore")
        .build();

Node.js

Cloud Datastore 用のクライアントライブラリをインストールして使用する方法については、Cloud Datastore のクライアントライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンスドキュメントをご覧ください。

const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

PHP

Cloud Datastore 用のクライアントライブラリをインストールして使用する方法については、Cloud Datastore のクライアントライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンスドキュメントをご覧ください。

$task = $datastore->entity('Task', [
    'category' => 'Personal',
    'done' => false,
    'priority' => 4,
    'description' => 'Learn Cloud Datastore'
]);

Python

Cloud Datastore 用のクライアントライブラリをインストールして使用する方法については、Cloud Datastore のクライアントライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンスドキュメントをご覧ください。

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

task = datastore.Entity(client.key("Task"))
task.update(
    {
        "category": "Personal",
        "done": False,
        "priority": 4,
        "description": "Learn Cloud Datastore",
    }
)

Ruby

Cloud Datastore 用のクライアントライブラリをインストールして使用する方法については、Cloud Datastore のクライアントライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンスドキュメントをご覧ください。

task = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 4
  t["description"] = "Learn Cloud Datastore"
end

エンティティをデータベースに保存するには、upsert（Datastore モードに存在するときにエンティティを上書きする場合）または insert（エンティティキーがまだ存在していない場合）を使用します。

ここでは、エンティティに対して upsert を実行する方法を示します。

C#

_db.Upsert(_sampleTask);

Go

key := datastore.IncompleteKey("Task", nil)
key, err := client.Put(ctx, key, task)

Java

Entity task = Entity.newBuilder(keyFactory.newKey("sampleTask")).build();
datastore.put(task);

Node.js

const taskKey = datastore.key('Task');
const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const entity = {
  key: taskKey,
  data: task,
};

await datastore.upsert(entity);
// Task inserted successfully.

PHP

$key = $datastore->key('Task', 'sampleTask');
$task = $datastore->entity($key, [
    'category' => 'Personal',
    'done' => false,
    'priority' => 4,
    'description' => 'Learn Cloud Datastore'
]);
$datastore->upsert($task);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

complete_key = client.key("Task", "sampleTask")

task = datastore.Entity(key=complete_key)

task.update(
    {
        "category": "Personal",
        "done": False,
        "priority": 4,
        "description": "Learn Cloud Datastore",
    }
)

client.put(task)

Ruby

# task_name = "sampleTask"
task = datastore.entity "Task", task_name do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 4
  t["description"] = "Learn Cloud Datastore"
end
datastore.save task

ここでは、エンティティに対して insert を実行する方法を示します。

C#

Entity task = new Entity()
{
    Key = _keyFactory.CreateIncompleteKey()
};
task.Key = _db.Insert(task);

Go

taskKey := datastore.NameKey("Task", "sampleTask", nil)
_, err := client.RunInTransaction(ctx, func(tx *datastore.Transaction) error {
	// We first check that there is no entity stored with the given key.
	var empty Task
	if err := tx.Get(taskKey, &empty); err != datastore.ErrNoSuchEntity {
		return err
	}
	// If there was no matching entity, store it now.
	_, err := tx.Put(taskKey, &task)
	return err
})

Java

Key taskKey = datastore.add(FullEntity.newBuilder(keyFactory.newKey()).build()).getKey();

Node.js

const taskKey = datastore.key('Task');
const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const entity = {
  key: taskKey,
  data: task,
};

datastore.insert(entity).then(() => {
  // Task inserted successfully.
});

PHP

$task = $datastore->entity('Task', [
    'category' => 'Personal',
    'done' => false,
    'priority' => 4,
    'description' => 'Learn Cloud Datastore'
]);
$datastore->insert($task);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

with client.transaction():
    incomplete_key = client.key("Task")

    task = datastore.Entity(key=incomplete_key)

    task.update(
        {
            "category": "Personal",
            "done": False,
            "priority": 4,
            "description": "Learn Cloud Datastore",
        }
    )

    client.put(task)

Ruby

datastore.transaction do |_tx|
  task = datastore.entity "Task" do |t|
    t["category"] = "Personal"
    t["done"] = false
    t["priority"] = 4
    t["description"] = "Learn Cloud Datastore"
  end
  datastore.save task
end

エンティティを取得する

データベースからエンティティを取得するには、そのキーを使用して lookup を実行します。

C#

Entity task = _db.Lookup(_sampleTask.Key);

Go

var task Task
taskKey := datastore.NameKey("Task", "sampleTask", nil)
err := client.Get(ctx, taskKey, &task)

Java

Entity task = datastore.get(taskKey);

Node.js

const taskKey = datastore.key('Task');
const [entity] = await datastore.get(taskKey);
// entity = {
//   category: 'Personal',
//   done: false,
//   priority: 4,
//   description: 'Learn Cloud Datastore',
//   [Symbol(KEY)]:
//    Key {
//      namespace: undefined,
//      id: '...',
//      kind: 'Task',
//      path: [Getter]
//    }
//   }
// };
console.log(entity);

PHP

$task = $datastore->lookup($key);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task", "sampleTask")
task = client.get(key)

Ruby

# task_name = "sampleTask"
task_key = datastore.key "Task", task_name
task = datastore.find task_key

エンティティを更新する

既存のエンティティに対して update を実行するには、事前に取得したエンティティのプロパティを変更し、キーを使用して結果を保存します。

C#

_sampleTask["priority"] = 5;
_db.Update(_sampleTask);

Go

taskKey := datastore.NameKey("Task", "sampleTask", nil)
tx, err := client.NewTransaction(ctx)
if err != nil {
	log.Fatalf("client.NewTransaction: %v", err)
}
var task Task
if err := tx.Get(taskKey, &task); err != nil {
	log.Fatalf("tx.Get: %v", err)
}
task.Priority = 5
if _, err := tx.Put(taskKey, &task); err != nil {
	log.Fatalf("tx.Put: %v", err)
}
if _, err := tx.Commit(); err != nil {
	log.Fatalf("tx.Commit: %v", err)
}

Java

Entity task;
Transaction txn = datastore.newTransaction();
try {
  task = Entity.newBuilder(txn.get(taskKey)).set("priority", 5).build();
  txn.put(task);
  txn.commit();
} finally {
  if (txn.isActive()) {
    txn.rollback();
  }
}

Node.js

const taskKey = datastore.key('Task');
const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const entity = {
  key: taskKey,
  data: task,
};

await datastore.update(entity);
// Task updated successfully.

PHP

$transaction = $datastore->transaction();
$key = $datastore->key('Task', 'sampleTask');
$task = $transaction->lookup($key);
$task['priority'] = 5;
$transaction->update($task);
$transaction->commit();

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

with client.transaction():
    key = client.key("Task", "sampleTask")
    task = client.get(key)

    task["done"] = True

    client.put(task)

Ruby

# task_name = "sampleTask"
datastore.transaction do |_tx|
  task = datastore.find "Task", task_name
  task["priority"] = 5
  datastore.save task
end

提供されたデータで既存のエンティティが上書きされます。オブジェクト全体をデータベースに送信する必要があります。エンティティが存在しない場合、更新は失敗します。エンティティを更新または作成する場合は、前述のとおり、upsert を使用します。トランザクションを使用すると、単一のアトミックトランザクションで get と update オペレーションを実行できます。

エンティティを削除する

エンティティを削除するには、エンティティのキーを指定して delete を実行します。

C#

_db.Delete(_sampleTask.Key);

Go

key := datastore.NameKey("Task", "sampletask", nil)
err := client.Delete(ctx, key)

Java

datastore.delete(taskKey);

Node.js

const taskKey = datastore.key('Task');
await datastore.delete(taskKey);
// Task deleted successfully.

PHP

$datastore->delete($taskKey);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task", "sampleTask")
client.delete(key)

Ruby

# task_name = "sampleTask"
task_key = datastore.key "Task", task_name
datastore.delete task_key

バッチオペレーション

Datastore モードの Firestore は、Datastore モードの 1 回の呼び出しで複数のオブジェクトを操作できるバッチオペレーションをサポートしています。

このようなバッチ呼び出しでは、サービス呼び出しの 1 回分のオーバーヘッドしか発生しないため、エンティティごとに個別の呼び出しを行うよりも高速になります。また、複数のエンティティグループを対象とする場合は、サーバー側で各エンティティグループの処理が並列に行われます。

たとえば、複数のエンティティに対して upsert を実行できます。

C#

var taskList = new[]
{
    new Entity()
    {
        Key = _keyFactory.CreateIncompleteKey(),
        ["category"] = "Personal",
        ["done"] = false,
        ["priority"] = 4,
        ["description"] = "Learn Cloud Datastore"
    },
    new Entity()
    {
        Key = _keyFactory.CreateIncompleteKey(),
        ["category"] = "Personal",
        ["done"] = "false",
        ["priority"] = 5,
        ["description"] = "Integrate Cloud Datastore"
    }
};
var keyList = _db.Upsert(taskList[0], taskList[1]);

Go

tasks := []*Task{
	{
		Category:    "Personal",
		Done:        false,
		Priority:    4,
		Description: "Learn Cloud Datastore",
	},
	{
		Category:    "Personal",
		Done:        false,
		Priority:    5,
		Description: "Integrate Cloud Datastore",
	},
}
keys := []*datastore.Key{
	datastore.IncompleteKey("Task", nil),
	datastore.IncompleteKey("Task", nil),
}

keys, err := client.PutMulti(ctx, keys, tasks)

Java

FullEntity<IncompleteKey> task1 =
    FullEntity.newBuilder(keyFactory.newKey())
        .set("category", "Personal")
        .set("done", false)
        .set("priority", 4)
        .set("description", "Learn Cloud Datastore")
        .build();
FullEntity<IncompleteKey> task2 =
    Entity.newBuilder(keyFactory.newKey())
        .set("category", "Personal")
        .set("done", false)
        .set("priority", 5)
        .set("description", "Integrate Cloud Datastore")
        .build();
List<Entity> tasks = datastore.add(task1, task2);
Key taskKey1 = tasks.get(0).getKey();
Key taskKey2 = tasks.get(1).getKey();

Node.js

const taskKey1 = this.datastore.key(['Task', 1]);
const taskKey2 = this.datastore.key(['Task', 2]);

const task1 = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const task2 = {
  category: 'Work',
  done: false,
  priority: 8,
  description: 'Integrate Cloud Datastore',
};

const entities = [
  {
    key: taskKey1,
    data: task1,
  },
  {
    key: taskKey2,
    data: task2,
  },
];

await datastore.upsert(entities);
// Tasks inserted successfully.

PHP

$result = $datastore->upsertBatch($tasks);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

task1 = datastore.Entity(client.key("Task", 1))

task1.update(
    {
        "category": "Personal",
        "done": False,
        "priority": 4,
        "description": "Learn Cloud Datastore",
    }
)

task2 = datastore.Entity(client.key("Task", 2))

task2.update(
    {
        "category": "Work",
        "done": False,
        "priority": 8,
        "description": "Integrate Cloud Datastore",
    }
)

client.put_multi([task1, task2])

Ruby

task_1 = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 4
  t["description"] = "Learn Cloud Datastore"
end

task_2 = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 5
  t["description"] = "Integrate Cloud Datastore"
end

tasks = datastore.save task_1, task_2
task_key_1 = tasks[0].key
task_key_2 = tasks[1].key

複数のエンティティに対して lookup を実行できます。

C#

var keys = new Key[] { _keyFactory.CreateKey(1), _keyFactory.CreateKey(2) };
var tasks = _db.Lookup(keys[0], keys[1]);

Go

var taskKeys []*datastore.Key // Populated with incomplete keys.
tasks := make([]*Task, len(taskKeys))
err := client.GetMulti(ctx, taskKeys, &tasks)

Java

Iterator<Entity> tasks = datastore.get(taskKey1, taskKey2);

Node.js

const taskKey1 = this.datastore.key(['Task', 1]);
const taskKey2 = this.datastore.key(['Task', 2]);

const keys = [taskKey1, taskKey2];

const [tasks] = await datastore.get(keys);
// Tasks retrieved successfully.
console.log(tasks);

PHP

$result = $datastore->lookupBatch($keys);
if (isset($result['found'])) {
    // $result['found'] is an array of entities.
} else {
    // No entities found.
}

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

keys = [client.key("Task", 1), client.key("Task", 2)]
tasks = client.get_multi(keys)

Ruby

# task_name_1 = "sampleTask1"
# task_name_2 = "sampleTask2"
task_key_1 = datastore.key "Task", task_name_1
task_key_2 = datastore.key "Task", task_name_2
tasks = datastore.find_all task_key_1, task_key_2

複数のエンティティを削除できます。

C#

var keys = new Key[] { _keyFactory.CreateKey(1), _keyFactory.CreateKey(2) };
_db.Delete(keys);

Go

err := client.DeleteMulti(ctx, taskKeys)

Java

datastore.delete(taskKey1, taskKey2);

Node.js

const taskKey1 = this.datastore.key(['Task', 1]);
const taskKey2 = this.datastore.key(['Task', 2]);

const keys = [taskKey1, taskKey2];

await datastore.delete(keys);
// Tasks deleted successfully.

PHP

$result = $datastore->deleteBatch($keys);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

keys = [client.key("Task", 1), client.key("Task", 2)]
client.delete_multi(keys)

Ruby

# task_name_1 = "sampleTask1"
# task_name_2 = "sampleTask2"
task_key_1 = datastore.key "Task", task_name_1
task_key_2 = datastore.key "Task", task_name_2
datastore.delete task_key_1, task_key_2

バッチオペレーションを実行しても、料金と割り当てに記載されている読み取り、書き込み、削除コストは変わりません。そのキーが存在するかどうかにかかわらず、バッチオペレーションに含まれるすべてのキーについて課金されます。

オペレーションに含まれるエンティティのサイズは、読み取り、書き込み、削除コストに影響しません。ただし、エンティティのサイズはストレージサイズの費用に影響します。

インクリメントとその他のプロパティ変換

increment などのプロパティ変換を使用して、プロパティをサーバーサイドで更新します。プロパティ変換を使用すると、現在の値を取得するためのクライアントサイドの読み取りオペレーションと、新しい値を決定するためのクライアントサイドの計算が不要になります。

Datastore モードでは、次のプロパティ変換がサポートされています。

increment
maximum
minimum
appendMissingElements
removeAllFromArray
setToServerValue(REQUEST_TIME)

次の例は、プロパティ変換を示しています。このオペレーションでは、指定された値だけプロパティが増分されます。

REST

POST https://datastore.googleapis.com/v1/projects/{projectId}:commit
{
  "mode": "NON_TRANSACTIONAL",
  "mutations": [
    {
      "propertyMask": {},  // Empty write mask indicates only transforms can change the entity.
      "propertyTransforms": [
        {
          "property": "quantity",
          "increment": {
            "integerValue": 2
          }
        },
        {
          "property": "inStock",
          "maximum": {
            "integerValue": 100
          }
        },
      ]
      "upsert": {
        "key": {
          "path": [
            {
              "kind": "Items",
              "name": "entity_1"
            }
          ]
        }
      }
    }
  ]
}

次の例では、サーバーがリクエストを処理した時刻（ミリ秒単位の精度）をプロパティ値に設定します。

REST

POST https://datastore.googleapis.com/v1/projects/{projectId}:commit
{
  "mode": "NON_TRANSACTIONAL",
  "mutations": [
    {
      "propertyMask": {},  // // Empty write mask indicates only transforms can change the entity.
      "propertyTransforms": [
        {
          "property": "timeField",
          "setToServerValue": "REQUEST_TIME"
        },
      ]
      "upsert": {
        "key": {
          "path": [
            {
              "kind": "Kind_1",
              "name": "entity_1"
            }
          ]
        }
      }
    }
  ]
}

次の例では、配列要素が欠落している場合に配列要素を追加します。

REST

POST https://datastore.googleapis.com/v1/projects/{projectId}:commit
{
  "mode": "NON_TRANSACTIONAL",
  "mutations": [
    {
      "propertyMask": {},  // Empty write mask indicates only transforms can change the entity.
      "propertyTransforms": [
        {
          "property": "arrayField",
          "appendMissingElements": {
            "values": [
              { "stringValue": "str" }, { "integerValue": 10 }
            ]
          }
        },
      ]
      "upsert": {
        "key": {
          "path": [
            {
              "kind": "Kind_1",
              "name": "entity_1"
            }
          ]
        }
      }
    }
  ]
}

`maximum` と `minimum` の混合タイプ

maximum プロパティ変換と minimum プロパティ変換は、整数値または double（浮動小数点数）値を入力として受け取ります。target プロパティの値は、整数または double 値にすることもできます。

プロパティが整数または double でない場合、またはプロパティが存在しない場合、変換によってプロパティが指定された入力値と型に設定されます。プロパティと入力値が混在する型（一方が整数で、もう一方が double）の場合に maximum オペレーションが適用されると、プロパティは大きい方のオペランドの型になります。minimum の場合、プロパティは小さい方のオペランドの型になります。

オペランドが同等（3 と 3.0 など）の場合、プロパティは変更されません。0、0.0、-0.0 はすべてゼロです。保存された値がゼロで、入力値がゼロの場合、maximum または minimum は常に保存された値になります。任意の数値と NaN の maximum または minimum は NaN です。

複数のミューテーションと `PropertyMask`

プロパティ変換は、リクエスト内の追加のミューテーションの後に順番に適用されます。PropertyMask は、insert、update、upsert のミューテーションを指定されたプロパティに制限しますが、プロパティ変換は制限しません。

たとえば、次のエンティティから始めます。

REST

entity: {
  "key" : {
    "path": [
      {
        "kind": "Kind_1",
        "name": "entity_1"
      }
    ]
  }
  "properties" : {
    "a": 1,
    "b": 2,
    "c": 3
  }
}

次のリクエストは、a と b の両方を更新し、プロパティ b にプロパティ変換を適用します。

POST https://datastore.googleapis.com/v1/projects/{projectId}:commit
{
  "mode": "NON_TRANSACTIONAL",
  "mutations": [
    {
      "propertyMask": {"a", "b"},  // update property a, b
      "update": {
        "key": {
          "path": [
            {
              "kind": "Kind_1",
              "name": "entity_1"
            }
          ]
        }
        "properties": {
          "a" : "new_value",
          "b" : -2
        }
      },
      "propertyTransforms": [
        {
          "property": "b",
          "increment": { 
            "integerValue": 2
          }
        }
      ]
    }
  ]
}

結果は次のようになります。

REST

entity: {
  "key" : {
    "path": [
      {
        "kind": "Kind_1",
        "name": "entity_1"
      }
    ]
  }
  "properties" : {
    "a": "new_value",
    "b": 0,
    "c": 3
  }
}

種類と識別子

各エンティティは特定の「種類」に属しています。「種類」とは、クエリでの使用を目的としてエンティティを分類するものです。たとえば、タスクリストアプリケーションでは、行うべき各タスクを Task という種類のエンティティで表現できます。

2 つのアンダースコア（__）で始まる種類名はすべて予約済みであり、使用できません。

識別子を割り当てる

種類に加え、各エンティティは作成時に割り当てられた識別子を持ちます。識別子はエンティティのキーの一部であるため、エンティティに永続的に割り当てられており、変更できません。識別子を割り当てる方法は 2 通りあります。

アプリケーションからエンティティの固有のキー名文字列を指定する。

エンティティキー文字列の最大サイズについては、上限をご覧ください。
エンティティに整数の数値 ID が自動的に割り当てられるように、Datastore モードの Firestore を設定する。
識別子の割り当てに関するベストプラクティスについては、ベストプラクティスのキーのセクションをご覧ください。

次の例では、種類が Task でキー名が「sampleTask」のキーを識別子として作成します。

C#

Key key = _db.CreateKeyFactory("Task").CreateKey("sampleTask");

Go

taskKey := datastore.NameKey("Task", "sampletask", nil)

Java

Key taskKey = datastore.newKeyFactory().setKind("Task").newKey("sampleTask");

Node.js

const taskKey = datastore.key(['Task', 'sampleTask']);

PHP

$taskKey = $datastore->key('Task', 'sampleTask');

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task", "sampleTask")

Ruby

# task_name = "sampleTask"
task_key = datastore.key "Task", task_name

Datastore モードでは、ID を自動的に割り当てることもできます。Datastore モードでは、ほぼ一様に分散されたランダムな未使用 ID のシーケンスが生成されます。各 ID は最大 16 桁の 10 進数になります。

次の例では、キー名を指定せずに種類が Task であるキーを作成します。不完全なキーを持つエンティティが Datastore モードに保存されると、エンティティの完全なキー（自動的に割り当てられた ID を含む）が返されます。

C#

Key incompleteKey = _db.CreateKeyFactory("Task").CreateIncompleteKey();
Key key = _db.AllocateId(incompleteKey);

Go

// A complete key is assigned to the entity when it is Put.
taskKey := datastore.IncompleteKey("Task", nil)

Java

KeyFactory keyFactory = datastore.newKeyFactory().setKind("Task");
Key taskKey = datastore.allocateId(keyFactory.newKey());

Node.js

const taskKey = datastore.key('Task');

PHP

$taskKey = $datastore->key('Task');

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task")

Ruby

task_key = datastore.key "Task"

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

独自の数値 ID を割り当てる

高度なアプリケーションでは、キー名の文字列を使用したり数値 ID を自動生成したりする代わりに、作成したエンティティに独自の数値 ID を手動で割り当てることができます。ただし、手動で作成した数値 ID を Datastore モードが別のエンティティに割り当てないようにする方法はない点に注意してください。このような競合を回避する唯一の方法は、allocateIds() メソッドを使ってアプリケーションで ID のブロックを取得することです。

Datastore モードの自動 ID 生成ツールは、このメソッドによって割り当てられた ID を追跡し、同じ ID が別のエンティティで使用されないようにします。競合を心配せずに、このような ID を安全に使用できます。allocateIds() メソッドで返される値を手動で選択することはできません。allocateIds() で返される値は、Datastore モードによって割り当てられます。

祖先パス

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

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

[User:alice, TaskList:default, Task:sampleTask]

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

[User:alice]

親のレベル

親のレベルを使用してデータを整理します。たとえば、アプリケーションで Task エンティティを TaskList エンティティで整理する場合、次のように親のレベルを 1 つ使用します。

C#

Key rootKey = _db.CreateKeyFactory("TaskList").CreateKey("default");
Key key = new KeyFactory(rootKey, "Task").CreateKey("sampleTask");

Go

parentKey := datastore.NameKey("TaskList", "default", nil)
taskKey := datastore.NameKey("Task", "sampleTask", parentKey)

Java

Key taskKey =
    datastore
        .newKeyFactory()
        .addAncestors(PathElement.of("TaskList", "default"))
        .setKind("Task")
        .newKey("sampleTask");

Node.js

const taskKey = datastore.key([
  'TaskList',
  'default',
  'Task',
  'sampleTask',
]);

PHP

$taskKey = $datastore->key('TaskList', 'default')
    ->pathElement('Task', 'sampleTask');

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("TaskList", "default", "Task", "sampleTask")
# Alternatively
parent_key = client.key("TaskList", "default")
key = client.key("Task", "sampleTask", parent=parent_key)

Ruby

# task_list_name = "default"
# task_name = "sampleTask"
task_key = datastore.key [["TaskList", task_list_name], ["Task", task_name]]

まず Task エンティティを User エンティティで整理し、次に TaskList エンティティで整理するアプリケーションでは、親のレベルを複数使用します。

C#

Key rootKey = _db.CreateKeyFactory("User").CreateKey("Alice");
Key taskListKey = new KeyFactory(rootKey, "TaskList").CreateKey("default");
Key key = new KeyFactory(taskListKey, "Task").CreateKey("sampleTask");

Go

userKey := datastore.NameKey("User", "alice", nil)
parentKey := datastore.NameKey("TaskList", "default", userKey)
taskKey := datastore.NameKey("Task", "sampleTask", parentKey)

Java

KeyFactory keyFactory =
    datastore
        .newKeyFactory()
        .addAncestors(PathElement.of("User", "Alice"), PathElement.of("TaskList", "default"))
        .setKind("Task");
Key taskKey = keyFactory.newKey("sampleTask");

Node.js

const taskKey = datastore.key([
  'User',
  'alice',
  'TaskList',
  'default',
  'Task',
  'sampleTask',
]);

PHP

$taskKey = $datastore->key('User', 'alice')
    ->pathElement('TaskList', 'default')
    ->pathElement('Task', 'sampleTask');

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("User", "alice", "TaskList", "default", "Task", "sampleTask")

Ruby

# user_name = "alice"
# task_list_name = "default"
# task_name = "sampleTask"
task_key = datastore.key([
                           ["User", user_name],
                           ["TaskList", task_list_name],
                           ["Task", task_name]
                         ])

上記の例に示すように、親を持つエンティティを作成するときは親の完全な祖先パスを指定します。

ユーザープロフィールを維持するアプリケーションでは、ユーザープロフィールデータに対して親のレベルが 1 つだけ必要となる場合があります。たとえば、Profile エンティティに対して、単一レベルの User 祖先パスを使用します。

[User:alice, Profile:public]

会議室のスケジュール設定を行うアプリケーションでは、親のレベルが複数必要になります。たとえば、Room エンティティの祖先パスとして Building/Floor 祖先パスのレベルを複数使用します。

[Building:C, Floor:1, Room:123]

エンティティグループ

エンティティグループは、ルートエンティティとその下位にあるすべてのエンティティで構成されています。アプリケーションでは通常、関連性の高いデータを整理する目的でエンティティグループを使用します。たとえば、あるプロダクトやユーザープロフィールに関するデータを保存するためにエンティティグループを使用できます。

プロパティと値の型

エンティティに関連付けられたデータ値は 1 つ以上のプロパティで構成されています。各プロパティは名前と 1 つ以上の値を持ちます。

プロパティは複数の型の値を持つことができるため、同じプロパティであってもエンティティによって値の型が異なる場合があります。プロパティはインデックス付けされている場合とされていない場合があります（プロパティ p で並べ替えまたはフィルタリングを行うクエリでは、p がインデックス付けされていないエンティティは無視されます）。

次にプロパティの例をいくつか示します。

C#

Entity task = new Entity()
{
    Key = _db.CreateKeyFactory("Task").CreateKey("sampleTask"),
    ["category"] = "Personal",
    ["created"] = new DateTime(1999, 01, 01, 0, 0, 0, DateTimeKind.Utc),
    ["done"] = false,
    ["priority"] = 4,
    ["percent_complete"] = 10.0,
    ["description"] = new Value()
    {
        StringValue = "Learn Cloud Datastore",
        ExcludeFromIndexes = true
    },
};

Go

type Task struct {
	Category        string
	Done            bool
	Priority        int
	Description     string `datastore:",noindex"`
	PercentComplete float64
	Created         time.Time
}
task := &Task{
	Category:        "Personal",
	Done:            false,
	Priority:        4,
	Description:     "Learn Cloud Datastore",
	PercentComplete: 10.0,
	Created:         time.Now(),
}

Java

Entity task =
    Entity.newBuilder(taskKey)
        .set("category", "Personal")
        .set("created", Timestamp.now())
        .set("done", false)
        .set("priority", 4)
        .set("percent_complete", 10.0)
        .set(
            "description",
            StringValue.newBuilder("Learn Cloud Datastore").setExcludeFromIndexes(true).build())
        .build();

Node.js

const task = [
  {
    name: 'category',
    value: 'Personal',
  },
  {
    name: 'created',
    value: new Date(),
  },
  {
    name: 'done',
    value: false,
  },
  {
    name: 'priority',
    value: 4,
  },
  {
    name: 'percent_complete',
    value: 10.0,
  },
  {
    name: 'description',
    value: 'Learn Cloud Datastore',
    excludeFromIndexes: true,
  },
];

PHP

$task = $datastore->entity(
    $key,
    [
        'category' => 'Personal',
        'created' => new DateTime(),
        'done' => false,
        'priority' => 4,
        'percent_complete' => 10.0,
        'description' => 'Learn Cloud Datastore'
    ],
    ['excludeFromIndexes' => ['description']]
);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

import datetime

key = client.key("Task")
task = datastore.Entity(key, exclude_from_indexes=("description",))
task.update(
    {
        "category": "Personal",
        "description": "Learn Cloud Datastore",
        "created": datetime.datetime.now(tz=datetime.timezone.utc),
        "done": False,
        "priority": 4,
        "percent_complete": 10.5,
    }
)
client.put(task)

Ruby

task = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["created"] = Time.now
  t["done"] = false
  t["priority"] = 4
  t["percent_complete"] = 10.0
  t["description"] = "Learn Cloud Datastore"
  t.exclude_from_indexes! "description", true
end

配列プロパティ

複数の値を持つプロパティは「配列プロパティ」と呼ばれます。次の例には 2 つの配列プロパティが含まれています。1 つ目は tags という名前で、値として fun と programming を持ちます。2 つ目は collaborators という名前で、値として alice と bob を持ちます。

C#

Entity task = new Entity()
{
    Key = _db.CreateKeyFactory("Task").CreateKey("sampleTask"),
    ["collaborators"] = new ArrayValue() { Values = { "alice", "bob" } },
    ["tags"] = new ArrayValue() { Values = { "fun", "programming" } }
};

Go

type Task struct {
	Tags          []string
	Collaborators []string
}
task := &Task{
	Tags:          []string{"fun", "programming"},
	Collaborators: []string{"alice", "bob"},
}

Java

Entity task =
    Entity.newBuilder(taskKey)
        .set("tags", "fun", "programming")
        .set("collaborators", ListValue.of("alice", "bob"))
        .build();

Node.js

const task = {
  tags: ['fun', 'programming'],
  collaborators: ['alice', 'bob'],
};

PHP

$task = $datastore->entity(
    $key,
    [
        'tags' => ['fun', 'programming'],
        'collaborators' => ['alice', 'bob']
    ]
);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task")
task = datastore.Entity(key)
task.update({"tags": ["fun", "programming"], "collaborators": ["alice", "bob"]})

Ruby

# task_name = "sampleTask"
task = datastore.entity "Task", task_name do |t|
  t["tags"] = ["fun", "programming"]
  t["collaborators"] = ["alice", "bob"]
end

配列プロパティは、等式フィルタを使ったクエリを実行するときなどに役立ちます。この場合、プロパティのいずれかの値がフィルタで指定した値と一致すると、そのエンティティはクエリの条件を満たしていることになります。配列プロパティの詳細と既知の問題については、クエリをご覧ください。

サポートされている値の型

プロパティは、エンティティのプロパティ名と値を格納する string/value マップとして保存されます。サポートされている値の型は次のとおりです。

32 ビットの整数

REST API
- フィールド名: entityValue
- 型: 整数 integerValue を持つ単一のプロパティ __int__ を含む JSON エンティティマップ
RPC API
- フィールド名: entity_value
- type: integer_value を含む単一のプロパティ __int__ を含む Entity メッセージ
並べ替え順: 数値

64 ビット整数

REST API
- フィールド名: integerValue
- 型: 数値または文字列。数値として正確に表現できない整数については文字列を使用します。
RPC API
- フィールド名: integer_value
- 型: int64
並べ替え順: 数値

配列

REST API
- フィールド名: arrayValue
- 型: JSON の Value オブジェクトの配列を含む ArrayValue オブジェクト
- 配列プロパティを割り当てるには arrayValue フィールド（ArrayValue 型）を使用して、その values フィールドを値の配列に設定します。プロパティのインデックスを解除するには、プロパティの value オブジェクトの excludeFromIndexes フィールドを true に設定します。
RPC API
- フィールド名: array_value
- 型: 1 つまたは複数の Value メッセージを含む ArrayValue メッセージ
- 配列プロパティを割り当てるには、array_value フィールド（ArrayValue 型）を使用して、その values フィールドに複数の Value オブジェクトを取り込みます。プロパティのインデックスを解除するには、Value の exclude_from_indexes フィールドを true に設定します。
並べ替え順: なし
注: 他の配列値は格納できません。値のインスタンスに meaning または exclude_from_indexes を設定しないでください。

ブール値

REST API
- フィールド名: booleanValue
- 型: true または false
RPC API
- フィールド名: boolean_value
- 型: bool
並べ替え順序: false<true

BSON タイムスタンプ

REST API
- フィールド名: entityValue
- 型: 整数プロパティ seconds と increment を持つプロパティ __request_timestamp__ を含む JSON エンティティマップ
RPC API
- フィールド名: entity_value
- 型: seconds と increment を含む BSON タイムスタンプを表す Entity メッセージ
並べ替え順: 日時順
注: Unix 秒と増分カウンタで構成される 64 ビットのタイムスタンプ値。

バイト（Blob）

REST API
- フィールド名: blobValue
- 型: 文字列。base64 でエンコードされている必要があります。
RPC API
- フィールド名: blob_value
- 型: bytes
並べ替え順: バイト順
注: プロパティがインデックス付けされている場合は最大 1,500 バイト、それ以外の場合は最大 1,048,487 バイト（1 MiB - 89 バイト）。

サブタイプを含むバイト数

REST API
- フィールド名: entityValue
- 型: base64 でエンコードされた blobValue（データにサブタイプバイトが付加されたもの）を含む単一のプロパティ __binary__ を含む JSON エンティティマップ
RPC API
- フィールド名: entity_value
- type: blob_value（データの前にサブタイプバイトが付加されたもの）を含む単一のプロパティ __binary__ を含む Entity メッセージ
並べ替え順序: バイト順（サブタイプ、値）
注: BSON サブタイプインジケーターを含むバイナリバイトシーケンス。

日付と時刻（タイムスタンプ）

REST API
- フィールド名: timestampValue
- 型: 文字列（ミリ秒単位の RFC 3339 フォーマット、2013-05-14T00:01:00.234Z など）
RPC API
- フィールド名: timestamp_value
- 型: Timestamp
並べ替え順: 日時順
注:
- Datastore モードに保存した場合、精度はマイクロ秒までになり、それより下の桁は切り捨てられます。
- 射影クエリの一部として返される場合、Datastore モードはタイムスタンプ値をマイクロ秒の整数値に変換します。

Decimal128

REST API
- フィールド名: entityValue
- 型: stringValue を含む単一のプロパティ __decimal128__ を含む JSON エンティティマップ
RPC API
- フィールド名: entity_value
- type: string_value を含む単一のプロパティ __decimal128__ を含む Entity メッセージ
並べ替え順: 数値
注: 高精度演算用の 128 ビット 10 進浮動小数点数。

Double（浮動小数点数）

REST API
- フィールド名: doubleValue
- 型: 数値
RPC API
- フィールド名: double_value
- 型: double
並べ替え順: 数値
注: 64 ビット倍精度、IEEE 754

埋め込みエンティティ

REST API
- フィールド名: entityValue
- 型: JSON エンティティ
RPC API
- フィールド名: entity_value
- 型: Entity メッセージ
並べ替え順: なし
注: インデックス付けされている場合は、サブプロパティに対してクエリを実行できます。この値をインデックス付けから除外した場合、すべてのサブプロパティもインデックス付けから除外されます。

地理的座標

REST API
- フィールド名: geoPointValue
- 型: JSON の緯度 / 経度のペア
RPC API
- フィールド名: geo_point_value
- 型: LatLng メッセージ
並べ替え順: 緯度、経度の順

キー

REST API
- フィールド名: keyValue
- 型: JSON の Datastore モードキー
RPC API
- フィールド名: key_value
- 型: Key メッセージ
並べ替え順: パス要素順（種類、識別子、種類、識別子...）

MaxKey

REST API
- フィールド名: entityValue
- 型: nullValue を含む単一のプロパティ __max__ を含む JSON エンティティマップ
RPC API
- フィールド名: entity_value
- type: null_value を含む単一のプロパティ __max__ を含む Entity メッセージ

MinKey

REST API
- フィールド名: entityValue
- 型: nullValue を含む単一のプロパティ __min__ を含む JSON エンティティマップ
RPC API
- フィールド名: entity_value
- type: null_value を含む単一のプロパティ __min__ を含む Entity メッセージ

Null

REST API
- フィールド名: nullValue
- 型: null
RPC API
- フィールド名: null_value
- 型: NullValue
並べ替え順: なし

ObjectId

REST API
- フィールド名: entityValue
- 型: stringValue（小文字の 16 進数文字列）を含む単一のプロパティ __oid__ を含む JSON エンティティマップ
RPC API
- フィールド名: entity_value
- type: string_value を含む単一のプロパティ __oid__ を含む Entity メッセージ
並べ替え順: 12 バイトのシーケンス

正規表現

REST API
- フィールド名: entityValue
- 型: pattern と options のプロパティを持つ __regex__ を含む JSON エンティティマップ
RPC API
- フィールド名: entity_value
- type: pattern プロパティと options プロパティを持つ正規表現を表す Entity メッセージ
並べ替え順: パターン、オプションの順

テキスト文字列

REST API
- フィールド名: stringValue
- 型: 文字列
RPC API
- フィールド名: string_value
- 型: string
並べ替え順: UTF-8 でエンコードされたバイト順
注: プロパティがインデックス付けされている場合は最大 1,500 バイト、それ以外の場合は最大 1,048,487 バイト（1 MiB - 89 バイト）。

値の型の順序付け

型が混合した値を持つプロパティをクエリで扱う場合、Datastore モードでは、内部表現に基づく決定論的な順序付けが使用されます。この順序は次のとおりです。

Null 値
MinKey
32 ビット整数
64 ビット整数とタイムスタンプ
ブール値
バイト文字列と Unicode 文字列
サブタイプを含むバイト
倍精度浮動小数点数（NaN は最後に並べ替え）
地理的座標
Datastore モードキー
ObjectId
BSON タイムスタンプ
正規表現
Decimal128（NaN は最後に並べ替えられます）
MaxKey

エンティティ、プロパティ、キー コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

エンティティを操作する

エンティティの作成

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

エンティティを取得する

C#

Go

Java

Node.js

PHP

Python

Ruby

エンティティを更新する

C#

Go

Java

Node.js

PHP

Python

Ruby

エンティティを削除する

C#

Go

Java

Node.js

PHP

Python

Ruby

バッチ オペレーション

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

インクリメントとその他のプロパティ変換

REST

REST

REST

maximum と minimum の混合タイプ

複数のミューテーションと PropertyMask

REST

REST

種類と識別子

識別子を割り当てる

エンティティ、プロパティ、キー

バッチオペレーション

`maximum` と `minimum` の混合タイプ

複数のミューテーションと `PropertyMask`

エンティティグループ