實體、屬性和金鑰

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

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

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

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

  • 實體的「命名空間」，可允許多租戶架構
  • 實體的種類，可將實體分類以進行查詢
  • 個別實體的「ID」，可以是以下其中一種：
    • 「索引鍵名稱」字串
    • 整數「數字 ID」
  • 選用的祖系路徑，可在資料庫階層結構中找到實體的位置

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

Firestore (Datastore 模式) 本身不會對實體結構強制執行任何限制，例如特定屬性是否具有特定類型的值；此項作業將由應用程式負責。

本頁面的程式碼片段是以開始使用 Firestore (Datastore 模式) 的範例做為建構依據。

使用實體

應用程式可使用 Datastore 模式的 Firestore 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

批次作業

Firestore (Datastore 模式) 支援批次作業版本，可透過單一 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 可利用兩種方式指派：

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

    如要瞭解實體鍵字串的最大大小，請參閱「限制」一文。

  • 您可以讓 Firestore (Datastore 模式) 自動指派整數的「數字 ID」給實體。

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

以下範例以索引鍵名稱「sampleTask」為 ID，建立屬於 Task 種類的索引鍵：

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 對應，其中包含實體的屬性名稱和值。支援以下類型的值：

陣列

  • REST API

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

  • RPC API

    • 欄位名稱：array_value
    • 類型：ArrayValue 訊息，其中包含一或多則 Value 訊息
    • 只要使用屬於 ArrayValue 類型的 array_value 欄位，並在其 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 訊息
  • 排序順序：按路徑元素 (種類、ID、種類、ID...)

空值

  • 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 模式資料庫會根據內部表示法使用確定性排序。以下是排序清單：

  1. 空值
  2. 定點數
    • 整數
    • 日期和時間
  3. 布林值
  4. 位元組字串
  5. Unicode 字串
  6. 浮點數
  7. NaN 值
  8. 地理點
  9. Datastore 模式索引鍵