Esta página foi traduzida pela API Cloud Translation.

Entidades, propriedades e chaves

Os objetos de dados no Firestore no modo Datastore são conhecidos como entidades. Uma entidade tem uma ou mais propriedades com nome, cada uma das quais pode ter um ou mais valores. As entidades do mesmo tipo não têm de ter as mesmas propriedades, e os valores de uma entidade para uma determinada propriedade não têm de ser todos do mesmo tipo de dados. (Se necessário, uma aplicação pode estabelecer e aplicar essas restrições no seu próprio modelo de dados.)

O modo Datastore suporta uma variedade de tipos de dados para valores de propriedades. Estas incluem, entre outras:

Números inteiros
Números de vírgula flutuante
Strings
Datas
Dados binários

Cada entidade numa base de dados do modo Datastore tem uma chave que a identifica de forma exclusiva. A chave é composta pelos seguintes componentes:

O espaço de nomes da entidade, que permite a multilocação
O tipo da entidade, que a categoriza para fins de consultas
Um identificador para a entidade individual, que pode ser
- Uma string de nome da chave
- um ID numérico inteiro
Um caminho de antepassados opcional que localiza a entidade na hierarquia da base de dados

Uma aplicação pode obter uma entidade individual da base de dados através da chave da entidade ou pode obter uma ou mais entidades emitindo uma consulta com base nas chaves ou nos valores das propriedades das entidades.

O Firestore no modo Datastore não aplica restrições à estrutura das entidades, como se uma determinada propriedade tem um valor de um tipo específico. Esta tarefa é deixada ao cuidado da aplicação.

Os fragmentos desta página baseiam-se no exemplo do artigo Introdução ao Firestore no modo Datastore.

Trabalhe com entidades

As aplicações podem usar a API Firestore no modo Datastore para criar, obter, atualizar e eliminar entidades. Se a aplicação conhecer a chave completa de uma entidade (ou puder derivá-la da respetiva chave principal, tipo e identificador), pode usar a chave para operar diretamente na entidade. Uma aplicação também pode obter a chave de uma entidade como resultado de uma consulta. Consulte o tópico Consultas para mais informações.

Crie uma entidade

Crie uma nova entidade inicializando-a e definindo as respetivas propriedades:

C#

Para saber como instalar e usar a biblioteca cliente do Cloud Datastore, consulte as bibliotecas cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# Cloud Datastore.

Para se autenticar no Cloud Datastore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

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

Go

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

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

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

PHP

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

Python

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

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

Pode guardar a entidade na base de dados através de upsert (que substitui uma entidade se já existir no modo Datastore) ou insert (que requer que a chave da entidade ainda não exista).

Veja como upsert uma entidade:

C#

_db.Upsert(_sampleTask);

Go

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

Java

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

Node.js

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

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

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

PHP

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

Python

from google.cloud import datastore

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

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

task = datastore.Entity(key=complete_key)

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

client.put(task)

Ruby

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

Veja como insert uma entidade:

C#

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

Go

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

Java

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

Node.js

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

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

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

PHP

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

Python

from google.cloud import datastore

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

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

    task = datastore.Entity(key=incomplete_key)

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

    client.put(task)

Ruby

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

Recupere uma entidade

Para obter uma entidade da base de dados, use a respetiva chave para uma pesquisa:

C#

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

Go

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

Java

Entity task = datastore.get(taskKey);

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

Atualize uma entidade

Para update uma entidade existente, modifique as propriedades da entidade obtida anteriormente e armazene-a através da chave:

C#

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

Go

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

Java

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

Node.js

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

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

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

PHP

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

Python

from google.cloud import datastore

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

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

    task["done"] = True

    client.put(task)

Ruby

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

Os dados fornecidos substituem a entidade existente. O objeto completo tem de ser enviado para a base de dados. Se a entidade não existir, a atualização falha. Se quiser atualizar ou criar uma entidade, use upsert, conforme descrito anteriormente. A utilização de uma transação permite-lhe realizar as operações get e update numa única transação atómica.

Elimine uma entidade

Com a chave de uma entidade, pode delete a entidade:

C#

_db.Delete(_sampleTask.Key);

Go

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

Java

datastore.delete(taskKey);

Node.js

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

PHP

$datastore->delete($taskKey);

Python

from google.cloud import datastore

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

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

Ruby

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

Operações em lote

O Firestore no modo Datastore suporta versões em lote das operações que lhe permitem operar em vários objetos numa única chamada do modo Datastore.

Estas chamadas em lote são mais rápidas do que fazer chamadas separadas para cada entidade individual, porque incorrem na sobrecarga de apenas uma chamada de serviço. Se estiverem envolvidos vários grupos de entidades, o trabalho de todos os grupos é realizado em paralelo no lado do servidor.

Por exemplo, pode upsert várias entidades:

C#

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

Go

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

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

Java

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

Node.js

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

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

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

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

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

PHP

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

Python

from google.cloud import datastore

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

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

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

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

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

client.put_multi([task1, task2])

Ruby

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

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

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

Pode pesquisar várias entidades:

C#

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

Go

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

Java

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

Node.js

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

const keys = [taskKey1, taskKey2];

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

Pode eliminar várias entidades:

C#

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

Go

err := client.DeleteMulti(ctx, taskKeys)

Java

datastore.delete(taskKey1, taskKey2);

Node.js

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

const keys = [taskKey1, taskKey2];

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

As operações em lote não alteram os custos de leitura, escrita ou eliminação, que estão documentados em Preços e quota. É-lhe cobrado o valor de cada chave numa operação em lote, quer a chave exista ou não.

A dimensão das entidades envolvidas numa operação não afeta os custos de leitura, escrita nem eliminação. No entanto, o tamanho das entidades afeta os custos de tamanho do armazenamento.

Incremento e outras transformações de propriedades

Use transformações de propriedades, como increment, para fazer atualizações do lado do servidor a uma propriedade. Uma transformação de propriedade evita uma operação de leitura adicional no lado do cliente para obter o valor atual e evita um cálculo no lado do cliente para determinar o novo valor.

O modo Datastore suporta as seguintes transformações de propriedades:

increment
maximum
minimum
appendMissingElements
removeAllFromArray
setToServerValue(REQUEST_TIME)

O exemplo seguinte demonstra uma transformação de propriedade. Esta operação incrementa as propriedades pelos valores especificados:

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"
            }
          ]
        }
      }
    }
  ]
}

O exemplo seguinte define um valor da propriedade para a hora em que o servidor processou o pedido com precisão de milissegundos.

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"
            }
          ]
        }
      }
    }
  ]
}

O exemplo seguinte anexa elementos da matriz se estiverem em falta.

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"
            }
          ]
        }
      }
    }
  ]
}

Tipos mistos com `maximum` e `minimum`

As transformações de propriedades maximum e minimum aceitam um número inteiro ou um valor duplo (número de vírgula flutuante) como entrada. O valor na propriedade de destino também pode ser um número inteiro ou um valor duplo.

Se a propriedade não for um número inteiro ou um número de vírgula flutuante, ou se a propriedade não existir, a transformação define a propriedade para o valor e o tipo de entrada fornecidos. Se for aplicada uma operação maximum em que a propriedade e o valor de entrada são de tipos mistos (ou seja, um é um número inteiro e o outro é um número de vírgula flutuante), a propriedade assume o tipo do operando maior. Para minimum, a propriedade assume o tipo do operando mais pequeno.

Se os operandos forem equivalentes (por exemplo, 3 e 3,0), a propriedade não é alterada. 0, 0,0 e -0,0 são todos zero. O maximum ou o minimum de um valor guardado zero e um valor de entrada zero é sempre o valor guardado. O maximum ou minimum de qualquer valor numérico e NaN é NaN.

Várias mutações e `PropertyMask`

As transformações de propriedades são aplicadas sequencialmente após quaisquer mutações adicionais no pedido. Um PropertyMask restringe as mutações insert, update e upsert às propriedades especificadas, mas não restringe as transformações de propriedades.

Por exemplo, começando com a seguinte entidade:

REST

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

O pedido seguinte atualiza a e b e, em seguida, aplica uma transformação de propriedade à propriedade 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
          }
        }
      ]
    }
  ]
}

O resultado é o seguinte:

REST

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

Tipos e identificadores

Cada entidade é de um tipo específico, que categoriza a entidade para fins de consultas. Por exemplo, uma aplicação de lista de tarefas pode representar cada tarefa a concluir com uma entidade do tipo Task.

Todos os nomes de tipos que começam com dois sublinhados (__) estão reservados e não podem ser usados.

Atribua identificadores

Além de um tipo, cada entidade tem um identificador, atribuído quando a entidade é criada. Uma vez que faz parte da chave da entidade, o identificador está associado permanentemente à entidade e não pode ser alterado. Pode ser atribuído de duas formas:

A sua aplicação pode especificar a sua própria string de nome da chave para a entidade.

Para ver informações sobre o tamanho máximo da string da chave da entidade, consulte a secção Limites.
Pode fazer com que o Firestore no modo Datastore atribua automaticamente à entidade um ID numérico inteiro.
Para ver as práticas recomendadas sobre a atribuição de identificadores, consulte a secção Chaves nas práticas recomendadas.

O exemplo seguinte cria uma chave do tipo Task que usa um nome de chave, "sampleTask", como identificador:

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

O modo Datastore também pode atribuir IDs automaticamente. O modo Datastore gera uma sequência aleatória de IDs não usados que são distribuídos de forma aproximadamente uniforme. Cada ID pode ter até 16 dígitos decimais.

O exemplo seguinte cria uma chave com o tipo Task, sem usar um nome de chave. A chave completa (incluindo o ID atribuído automaticamente) da entidade é devolvida quando uma entidade com a chave incompleta é guardada no modo Datastore:

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

key = client.key("Task")

Ruby

task_key = datastore.key "Task"

Se quiser apresentar os IDs das entidades ao utilizador e/ou depender da respetiva ordem, a melhor opção é usar a atribuição manual.

Atribua o seu próprio ID numérico

Em vez de usar strings de nomes de chaves ou gerar IDs numéricos automaticamente, por vezes, as aplicações avançadas podem atribuir os seus próprios IDs numéricos manualmente às entidades que criam. Tenha em atenção, no entanto, que não existe nada que impeça uma base de dados do modo Datastore de atribuir um dos seus IDs numéricos manuais a outra entidade. A única forma de evitar estes conflitos é fazer com que a sua aplicação obtenha um bloco de IDs com o método allocateIds().

O gerador de IDs automático do modo Datastore acompanha os IDs que foram atribuídos com estes métodos e evita reutilizá-los para outra entidade, para que possa usar esses IDs em segurança sem conflitos. Não pode escolher manualmente os valores devolvidos pelo método allocateIds(). Os valores devolvidos por allocateIds() são atribuídos pelo modo Datastore.

Caminhos de antepassados

As entidades numa base de dados do modo Datastore formam um espaço estruturado hierarquicamente semelhante à estrutura de diretórios de um sistema de ficheiros. Quando cria uma entidade, pode designar opcionalmente outra entidade como a respetiva principal. A nova entidade é uma secundária da entidade principal (tenha em atenção que, ao contrário do que acontece num sistema de ficheiros, a entidade principal não tem de existir efetivamente). Uma entidade sem um elemento principal é uma entidade raiz. A associação entre uma entidade e a respetiva entidade principal é permanente e não pode ser alterada depois de a entidade ser criada. O modo Datastore nunca atribui o mesmo ID numérico a duas entidades com o mesmo elemento principal ou a duas entidades raiz (as que não têm um elemento principal).

Uma entidade pode ter vários níveis de antecessores e descendentes. O pai, o pai do pai, e assim sucessivamente, de uma entidade são os seus ancestrais; os filhos, os filhos dos filhos, e assim sucessivamente, são os seus descendentes. A sequência de entidades que começa com uma entidade de raiz e prossegue do elemento principal para o elemento secundário, conduzindo a uma determinada entidade, constitui o caminho de antecessores dessa entidade. A chave completa que identifica a entidade consiste numa sequência de pares de tipo-identificador que especificam o respetivo caminho de antepassados e terminam com os da própria entidade:

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

Para uma entidade raiz, o caminho do antepassado está vazio e a chave consiste apenas no tipo e no identificador da própria entidade:

[User:alice]

Níveis de publicadores superiores

Use níveis de elementos principais para organizar os seus dados. Por exemplo, se a sua aplicação organizar Task entidades por TaskList entidades, use um nível principal:

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

Se a sua aplicação organizar primeiro as entidades Task por entidades User e, em seguida, por entidades TaskList, use vários níveis de elementos principais:

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

Conforme mostrado no exemplo anterior, quando cria uma entidade com um elemento principal, especifica o caminho de antepassados completo do elemento principal.

Uma aplicação que mantém perfis de utilizadores pode exigir apenas um nível de principal para os dados do perfil de utilizador. Por exemplo, use um caminho de antepassado de nível único User para entidades Profile:

[User:alice, Profile:public]

Uma aplicação que faculte o agendamento de salas de conferências pode exigir vários níveis de elementos superiores, como um caminho de antepassados de vários níveis para entidades Building/FloorRoom:

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

Grupos de entidades

Um grupo de entidades consiste numa entidade raiz e em todos os respetivos descendentes. Normalmente, as aplicações usam grupos de entidades para organizar dados altamente relacionados. Por exemplo, uma aplicação pode usar um grupo de entidades para armazenar dados sobre um produto ou um perfil de utilizador.

Propriedades e tipos de valores

Os valores de dados associados a uma entidade consistem numa ou mais propriedades. Cada propriedade tem um nome e um ou mais valores.

Uma propriedade pode ter valores de mais do que um tipo, e duas entidades podem ter valores de tipos diferentes para a mesma propriedade. Uma propriedade pode ser indexada ou não indexada (as consultas que ordenam ou filtram uma propriedade p ignoram as entidades em que p não está indexada).

Algumas propriedades de exemplo:

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

import datetime

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

Ruby

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

Propriedades da matriz

Uma propriedade com mais de um valor é denominada propriedade de matriz. Este exemplo contém duas propriedades de matriz. O primeiro chama-se tags com os valores fun e programming. O segundo chama-se collaborators e tem os valores alice e bob.

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

As propriedades de matriz podem ser úteis, por exemplo, quando executa consultas com filtros de igualdade: uma entidade satisfaz a consulta se algum dos respetivos valores para uma propriedade corresponder ao valor especificado no filtro. Para mais detalhes sobre as propriedades de matriz, incluindo problemas que deve ter em atenção, consulte o tópico Consultas.

Tipos de valores compatíveis

As propriedades são armazenadas como um mapa string/value que contém os nomes e os valores das propriedades da entidade. Os seguintes tipos são suportados para valores:

Matriz

API REST
- Nome do campo: arrayValue
- type: um objeto ArrayValue que contém uma matriz de objetos JSON Value
- Pode atribuir uma propriedade de matriz usando o campo arrayValue, que é do tipo ArrayValue, e definindo o respetivo campo values para uma matriz de valores. Para que uma propriedade não seja indexada, defina o campo excludeFromIndexes do objeto de valor da propriedade como true.
API RPC
- Nome do campo: array_value
- tipo: uma mensagem ArrayValue que contém uma ou mais mensagens Value
- Pode atribuir uma propriedade de matriz através do campo array_value, que é do tipo ArrayValue, e preencher o respetivo campo values com vários objetos Value. Para que uma propriedade não seja indexada, defina o campo exclude_from_indexes de Value como true.
Ordenação: nenhuma
Notas: não pode conter outro valor de matriz. A instância de valor não pode definir meaning nem exclude_from_indexes.

Booleano

API REST
- Nome do campo: booleanValue
- tipo: true ou false
API RPC
- Nome do campo: boolean_value
- type: bool
Ordenação: false<true

Blob

API REST
- Nome do campo: blobValue
- type: string. Tem de estar codificado em Base64.
API RPC
- Nome do campo: blob_value
- type: bytes
Ordenação: ordem dos bytes
Notas: até 1500 bytes se a propriedade estiver indexada, até 1 048 487 bytes (1 MiB - 89 bytes) caso contrário.

Data e hora

API REST
- Nome do campo: timestampValue
- tipo: string (com formato RFC 3339, com milissegundos, por exemplo, 2013-05-14T00:01:00.234Z)
API RPC
- Nome do campo: timestamp_value
- type: Timestamp
Ordenação: cronológica
Notas:
- Quando armazenado no modo Datastore, é preciso apenas até aos microssegundos. Qualquer precisão adicional é arredondada para baixo.
- Quando devolvido como parte de uma consulta de projeção, o modo Datastore converte valores de data/hora em valores inteiros de microssegundos.

Entidade incorporada

API REST
- Nome do campo: entityValue
- type: uma entidade JSON
API RPC
- Nome do campo: entity_value
- escrever: uma Entity mensagem
Ordenação: nenhuma
Notas: quando são indexadas, pode consultar as subpropriedades. Se excluir este valor da indexação, todas as subpropriedades também são excluídas da indexação.

Número de vírgula flutuante

API REST
- Nome do campo: doubleValue
- type: number
API RPC
- Nome do campo: double_value
- type: double
Ordenação: numérica
Notas: precisão dupla de 64 bits, IEEE 754

Ponto geográfico

API REST
- Nome do campo: geoPointValue
- type: um par de latitude/longitude JSON
API RPC
- Nome do campo: geo_point_value
- tipo: uma mensagem LatLng
Ordem de ordenação: por latitude e, em seguida, longitude

Número inteiro

API REST
- Nome do campo: integerValue
- tipo: número ou string. Use strings para números inteiros que não podem ser representados exatamente como números.
API RPC
- Nome do campo: integer_value
- type: int64
Ordenação: numérica

Chave

API REST
- Nome do campo: keyValue
- type: uma chave do modo Datastore JSON
API RPC
- Nome do campo: key_value
- tipo: uma mensagem Key
Ordem de classificação: por elementos do caminho (tipo, identificador, tipo, identificador...)

Nulo

API REST
- Nome do campo: nullValue
- type: null
API RPC
- Nome do campo: null_value
- type: NullValue
Ordenação: nenhuma

String de texto

API REST
- Nome do campo: stringValue
- type: cadeia
API RPC
- Nome do campo: string_value
- type: string
Ordem de classificação: ordem de bytes codificada em UTF-8
Notas: até 1500 bytes se a propriedade estiver indexada, até 1 048 487 bytes (1 MiB - 89 bytes) caso contrário.

Ordenação do tipo de valor

Quando uma consulta envolve uma propriedade com valores de tipos mistos, uma base de dados do modo Datastore usa uma ordenação determinística com base nas representações internas. A seguinte lista mostra a ordem:

Valores nulos
Números de ponto fixo
- Números inteiros
- Datas e horas
Valores booleanos
Strings de bytes
Strings Unicode
Números de vírgula flutuante
Valores NaN
Pontos geográficos
Chaves do modo Datastore

Entidades, propriedades e chaves Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Trabalhe com entidades

Crie uma entidade

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

Recupere uma entidade

C#

Go

Java

Node.js

PHP

Python

Ruby

Atualize uma entidade

C#

Go

Java

Node.js

PHP

Python

Ruby

Elimine uma entidade

C#

Go

Java

Node.js

PHP

Python

Ruby

Operações em lote

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

Incremento e outras transformações de propriedades

REST

REST

REST

Tipos mistos com maximum e minimum

Várias mutações e PropertyMask

REST

REST

Tipos e identificadores

Atribua identificadores

Entidades, propriedades e chaves

Tipos mistos com `maximum` e `minimum`

Várias mutações e `PropertyMask`