このページは Cloud Translation API によって翻訳されました。

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

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 プロパティの変換では、整数値または倍精度（浮動小数点数）値のいずれかが入力として使用されます。ターゲットプロパティの値は、整数値または倍精度浮動小数点数値にすることもできます。

プロパティが整数または倍精度浮動小数点数でない場合、またはプロパティが存在しない場合、変換はプロパティを指定された入力値と型に設定します。プロパティと入力値の型が混在している（一方が整数で、もう一方が倍精度浮動小数点数）場合に 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 マップとして保存されます。サポートされている値の型は次のとおりです。

配列

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

Blob

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

日時

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

埋め込みエンティティ

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

浮動小数点数

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

地理的座標

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

整数

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

キー

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

Null

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

テキスト文字列

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

値の型の順序付け

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

Null 値
固定小数点数
- 整数
- 日時型
ブール値
バイト文字列
Unicode 文字列
浮動小数点数
NaN 値
地理的座標
Datastore モードキー

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

エンティティを操作する

エンティティの作成

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`

エンティティグループ