實體、屬性和金鑰

Datastore 模式的 Firestore 資料物件稱為「實體」。實體有一或多個具名「屬性」，每個屬性可有一或多個值。同種類型的實體不一定要有相同的屬性，而且實體在特定屬性的值也不必全都是相同的資料類型。(如有必要，應用程式可在其資料模型內建立並強制執行這類限制)。

Datastore 模式支援多種屬性值資料類型。包括：

  • 整數
  • 浮點數
  • 字串
  • 日期
  • 二進位資料

Datastore 模式資料庫中的每個實體都有專門用來識別該實體的「索引鍵」。索引鍵由下列元件組成：

  • 實體的命名空間，可支援多租戶架構
  • 實體的種類，用於分類實體以利查詢
  • 個別實體的ID，可以是
    • 「索引鍵名稱」字串
    • 整數「數字 ID」
  • 選用的上階路徑，用於在資料庫階層中找出實體

應用程式可以使用實體的索引鍵，從資料庫擷取個別實體，也可以根據實體的索引鍵或屬性值發出查詢，擷取一或多個實體。

Datastore 模式的 Firestore 本身不會對實體結構強制執行任何限制，例如特定屬性是否具有特定類型的值，這項工作會交由應用程式處理。

本頁的程式碼片段是以「開始使用 Datastore 模式的 Firestore」中的範例為基礎。

使用實體

應用程式可以使用 Firestore in Datastore 模式 API 建立、擷取、更新及刪除實體。如果應用程式知道實體的完整索引鍵 (或是可從父系索引鍵、種類和 ID 中取得)，即可在該實體上使用索引鍵直接作業。應用程式也可以透過查詢取得實體索引鍵，詳細資訊請參閱查詢主題。

建立實體

建立新實體的方式是初始化該實體並設定其屬性：

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 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore PHP API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Python API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore C# API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

_db.Upsert(_sampleTask);

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Go API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Java API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Node.js API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore PHP API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Python API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Ruby API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

# 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#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore C# API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Go API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Java API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Node.js API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore PHP API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Python API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Ruby API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

擷取實體

如要從資料庫擷取實體，請使用實體的索引鍵進行查詢：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore C# API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Go API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Java API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

Entity task = datastore.get(taskKey);

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Node.js API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore PHP API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Python API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Ruby API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

更新實體

如要update現有實體，請修改先前擷取的實體屬性，並使用索引鍵儲存：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore C# API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Go API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Java API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Node.js API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore PHP API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Python API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Ruby API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

# 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#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore C# API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

_db.Delete(_sampleTask.Key);

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Go API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Java API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

datastore.delete(taskKey);

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Node.js API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore PHP API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

$datastore->delete($taskKey);

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Python API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Ruby API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

批次作業

Datastore 模式的 Firestore 支援批次版本的作業，可在單一 Datastore 模式呼叫中對多個物件執行作業。

這類批次呼叫只會產生一次服務呼叫的負擔，因此速度大於分別呼叫每一個實體。如果涉及多個實體群組，則會在伺服器端針對所有群組並行執行作業。

例如，您可以upsert多個實體：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore C# API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Go API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Java API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Node.js API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore PHP API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Python API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Ruby API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

您可以查詢多個實體：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore C# API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Go API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Java API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Node.js API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore PHP API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Python API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Ruby API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

# 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#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore C# API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Go API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

err := client.DeleteMulti(ctx, taskKeys)

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Java API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

datastore.delete(taskKey1, taskKey2);

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Node.js API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore PHP API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Python API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Ruby API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

# 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
  }
}

種類及 ID

每個實體都屬於特定種類，系統會根據種類將實體分類，以便執行查詢。舉例來說，工作清單應用程式可能會以 Task 類型的實體代表每項待完成工作。

以兩條底線 (__) 開頭的種類名稱均為保留名稱，不得使用。

指派 ID

除了種類以外，建立每個實體時還會指派實體的「ID」。因為 ID 屬於實體索引鍵的一部分，所以會與實體永久關聯，且無法變更。ID 可利用兩種方式指派：

  • 您的應用程式可以指定自身的實體「索引鍵名稱」字串。

    如要瞭解實體索引鍵字串的大小上限，請參閱「限制」。

  • 您可以讓 Datastore 模式的 Firestore 自動為實體指派整數數字 ID。

  • 如需指派 ID 的最佳做法，請參閱最佳做法中的「鍵」一節。

以下範例會建立種類為 Task 的金鑰，並使用金鑰名稱「sampleTask」做為 ID：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore C# API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Go API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Java API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Node.js API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore PHP API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Python API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Ruby API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Datastore 模式也可以自動指派 ID。Datastore 模式會產生隨機順序的未使用 ID，近乎均勻分佈。每個 ID 最長可達 16 個十進位數字。

以下範例會建立種類為 Task 的金鑰，但不使用金鑰名稱。在 Datastore 模式中儲存包含非完整索引鍵的實體時，會傳回該實體的完整索引鍵 (包含自動指派的 ID)：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore C# API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Go API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Java API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Node.js API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore PHP API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Python API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Ruby API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

task_key = datastore.key "Task"

如果您要向使用者顯示實體 ID，並/或依據其順序顯示，最理想的方式就是使用手動分配。

指派自己的數字 ID

進階應用程式有時可能會手動為建立的實體指派專屬數字 ID，而非使用索引鍵名稱字串或自動產生數字 ID。不過請注意，這樣就沒有辦法防止 Datastore 模式資料庫將其中一個手動數字 ID 指派給其他實體。如要避免這類衝突，唯一的方法是讓應用程式使用 allocateIds() 方法取得一組 ID。

Datastore 模式的自動 ID 產生器會追蹤使用這些方法分配的 ID，避免重複用於其他實體，這樣就能安全地使用這類 ID 而不會發生衝突。您無法手動選擇 allocateIds() 方法傳回的值。allocateIds() 傳回的值是由 Datastore 模式指派。

祖系路徑

Datastore 模式資料庫中的實體會形成階層結構空間，與檔案系統的目錄結構相似。建立實體時，您可以選擇將另一個實體指定為「上層」，新實體則是上層實體的「子項」 (請注意，與檔案系統不同，上層實體不一定要實際存在)。沒有父項的實體稱為「根實體」。實體與父項實體之間具有永久關聯性，一旦實體建立後就無法變更。Datastore 模式絕對不會將相同的數字 ID 指派給父項相同的兩個實體，也不會指派給兩個根實體 (即沒有父項的實體)。

一個實體可以有多個層級的上階和下階。實體的父項、父項的父項等，以此類推，都是其「祖系」；其子項、子項的子項等，以此類推，都是其「子系」。實體序列從根實體開始，由父項到子項，最後到達指定實體，這段序列構成該實體的「祖系路徑」。用於識別實體的完整索引鍵，是由一連串的種類 ID 配對組成，用於指定其祖系路徑，並以實體本身的種類 ID 配對結尾：

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

根實體的祖系路徑是空白路徑，其索引鍵只包含實體本身的種類與 ID。

[User:alice]

父項層級

請使用父項層級整理資料。舉例來說，如果應用程式依 TaskList 實體整理 Task 實體，請使用一層父項：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore C# API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Go API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Java API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Node.js API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore PHP API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Python API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Ruby API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如果應用程式先依 User 實體，再依 TaskList 實體整理 Task 實體，請使用多個層級的上層：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore C# API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Go API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Java API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Node.js API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore PHP API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Python API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Ruby API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如前例所示，建立具有父項的實體時，您必須指定父項的完整祖系路徑。

應用程式如會留存使用者個人資料，可能只需要一個用於使用者個人資料的父項層級。例如，針對 Profile 實體使用單一層級 User 上階路徑：

[User:alice, Profile:public]

提供會議室排程的應用程式可能需要多個層級的父項，例如 Room 實體的多層級 Building/Floor 祖系路徑：

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

實體群組

「實體群組」包含根實體和所有子系。應用程式通常會使用實體群組來整理高度相關的資料。例如，應用程式可能會使用實體群組儲存與某項產品或某個使用者個人資料相關的資料。

屬性和值類型

與實體相關聯的資料值由一或多個「屬性」組成。每個屬性各有一個名稱及一或多個值。

一個屬性可能會有多個類型的值，而兩個實體的相同屬性可能會有不同類型的值。屬性可能已建立索引或未建立索引 (排序或篩選屬性「p」的查詢將忽略「p」未建立索引的實體)。

以下列舉屬性範例：

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore C# API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Go API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Java API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Node.js API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore PHP API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Python API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Ruby API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Array 屬性

屬性如有一個以上的值，就稱為「陣列屬性」。此範例包含兩個陣列屬性。第一個名為 tags，值為 fun 和 programming。第二個欄位名稱為 collaborators，包含 alice 和 bob 兩個值。

C#

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore C# API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Go

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Go API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Java

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Java API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Node.js

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Node.js API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

PHP

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore PHP API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

Python

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Python API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

如要瞭解如何安裝及使用 Cloud Datastore 的用戶端程式庫，請參閱「Cloud Datastore 用戶端程式庫」。詳情請參閱 Cloud Datastore Ruby API 參考文件。

如要向 Cloud Datastore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

# 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
    • type：JSON 實體對應，包含單一屬性 __int__，整數為 integerValue
  • RPC API
    • 欄位名稱：entity_value
    • type：Entity 訊息，包含單一屬性 __int__，其值為 integer_value
  • 排序依據：數字

64 位元整數

  • REST API
    • 欄位名稱：integerValue
    • 類型：數字或字串。若是無法明確以數字表示的整數，請使用字串。
  • RPC API
    • 欄位名稱：integer_value
    • type: int64
  • 排序依據：數字

陣列

  • REST API

    • 欄位名稱：arrayValue
    • type：ArrayValue 物件，包含 JSON 值物件陣列
    • 您可以使用 arrayValue 欄位 (類型為 ArrayValue) 指派陣列屬性，並將其 values 欄位設為值陣列。如要取消屬性的索引，請將屬性值物件的 excludeFromIndexes 欄位設為 true。

  • RPC API

    • 欄位名稱：array_value
    • type：包含一或多個 Value 訊息的 ArrayValue 訊息
    • 您可以使用 array_value 欄位 (類型為 ArrayValue) 指派陣列屬性，並在 values 欄位中填入多個 Value 物件。如要取消索引屬性，請將 Value 的 exclude_from_indexes 欄位設為 true。

  • 排列順序：無

  • 附註：不能包含其他陣列值。值例項不得設定 meaning 或 exclude_from_indexes。

布林值

  • REST API
    • 欄位名稱：booleanValue
    • type：true 或 false
  • RPC API
    • 欄位名稱：boolean_value
    • type: bool
  • 排列順序：false<true

BSON 時間戳記

  • REST API
    • 欄位名稱：entityValue
    • type：JSON 實體對應，包含 __request_timestamp__ 屬性，以及整數屬性 seconds 和 increment
  • RPC API
    • 欄位名稱：entity_value
    • type：Entity 訊息，代表包含 seconds 和 increment 的 BSON 時間戳記
  • 排列順序：按時間順序
  • 附註：64 位元時間戳記值，包含 Unix 秒數和遞增計數器。

位元組 (Blob)

  • REST API
    • 欄位名稱：blobValue
    • 類型：字串。必須是 base64 編碼。
  • RPC API
    • 欄位名稱：blob_value
    • type: bytes
  • 排列順序：位元組順序
  • 附註：若已建立屬性的索引，上限是 1,500 個位元組，否則上限即為 1,048,487 個位元組 (1 MiB - 89 個位元組)。

含子類型的位元組

  • REST API
    • 欄位名稱：entityValue
    • type：JSON 實體對應，包含單一屬性 __binary__，並以 Base64 編碼 blobValue (子類型位元組會附加至資料)
  • RPC API
    • 欄位名稱：entity_value
    • type：Entity 訊息，包含單一屬性 __binary__，並帶有 blob_value (子類型位元組會附加至資料)
  • 排列順序：位元組順序 (子類型，然後是值)
  • 附註：二進位位元組序列，含有 BSON 子類型指標。

日期和時間 (時間戳記)

  • REST API
    • 欄位名稱：timestampValue
    • 類型：字串 (RFC 3339 格式，含毫秒，例如 2013-05-14T00:01:00.234Z)
  • RPC API
    • 欄位名稱：timestamp_value
    • type: Timestamp
  • 排列順序：按時間順序
  • 注意事項：
    • 儲存在 Datastore 模式中時，精確度只計算到微秒；無條件捨去任何其他精準度。
    • 在投影查詢中傳回時，Datastore 模式會將時間戳記值轉換成微秒整數值。

Decimal128

  • REST API
    • 欄位名稱：entityValue
    • type：JSON 實體對應，包含單一屬性 __decimal128__，其值為 stringValue
  • RPC API
    • 欄位名稱：entity_value
    • type：Entity 訊息，包含單一屬性 __decimal128__，其值為 string_value
  • 排序依據：數字
  • 附註：128 位元十進位浮點數，用於高精度算術。

雙精度 (浮點數)

  • REST API
    • 欄位名稱：doubleValue
    • 類型：數字
  • RPC API
    • 欄位名稱：double_value
    • type: double
  • 排列順序：數字
  • 附註：64 位元雙精確度，IEEE 754

嵌入實體

  • REST API
    • 欄位名稱：entityValue
    • 類型：JSON 實體
  • RPC API
    • 欄位名稱：entity_value
    • type：Entity 訊息
  • 排列順序：無
  • 附註：如有建立索引，可以查詢子屬性。若在建立索引時排除此值，也會一併排除所有子屬性。

地理點

  • REST API
    • 欄位名稱：geoPointValue
    • 類型：JSON 經度/緯度組合
  • RPC API
    • 欄位名稱：geo_point_value
    • type: a LatLng message
  • 排列順序：先依緯度，再依經度

鍵

  • REST API
    • 欄位名稱：keyValue
    • 類型：JSON Datastore 模式索引鍵
  • RPC API
    • 欄位名稱：key_value
    • type: a Key message
  • 排列順序：依路徑元素 (種類、ID、種類、ID...)

MaxKey

  • REST API
    • 欄位名稱：entityValue
    • type：JSON 實體對應，包含單一屬性 __max__，其值為 nullValue
  • RPC API
    • 欄位名稱：entity_value
    • type：Entity 訊息，包含單一屬性 __max__，其值為 null_value

MinKey

  • REST API
    • 欄位名稱：entityValue
    • type：JSON 實體對應，包含單一屬性 __min__，其值為 nullValue
  • RPC API
    • 欄位名稱：entity_value
    • type：Entity 訊息，包含單一屬性 __min__，其值為 null_value

空值

  • REST API
    • 欄位名稱：nullValue
    • 類型：null
  • RPC API
    • 欄位名稱：null_value
    • type: NullValue
  • 排列順序：無

ObjectId

  • REST API
    • 欄位名稱：entityValue
    • type：JSON 實體對應，包含單一屬性 __oid__，其值為 stringValue (小寫十六進位字串)
  • RPC API
    • 欄位名稱：entity_value
    • type：Entity 訊息，包含單一屬性 __oid__，其值為 string_value
  • 排列順序：依 12 位元組序列

規則運算式

  • REST API
    • 欄位名稱：entityValue
    • type：JSON 實體對應，包含 __regex__，以及 pattern 和 options 的屬性
  • RPC API
    • 欄位名稱：entity_value
    • type：Entity 訊息，代表具有 pattern 和 options 屬性的規則運算式
  • 排序順序：先依模式，再依選項

文字字串

  • REST API
    • 欄位名稱：stringValue
    • 類型：字串
  • RPC API
    • 欄位名稱：string_value
    • type: string
  • 排列順序：UTF-8 編碼位元組順序
  • 附註：若已建立屬性的索引，上限是 1,500 個位元組，否則上限即為 1,048,487 個位元組 (1 MiB - 89 個位元組)。

值類型排序

如果查詢涉及具有混合類型值的屬性，Datastore 模式資料庫會根據內部表示法使用確定性排序。順序如下：

  1. 空值
  2. MinKey
  3. 32 位元整數
  4. 64 位元整數和時間戳記
  5. 布林值
  6. 位元組字串和 Unicode 字串
  7. 含子類型的位元組
  8. 雙精度浮點數 (NaN 排在最後)
  9. 地理點
  10. Datastore 模式索引鍵
  11. ObjectId
  12. BSON 時間戳記
  13. 規則運算式
  14. Decimal128 (NaN 排序最後)
  15. MaxKey