Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Entités, propriétés et clés

Dans Cloud Firestore en mode Datastore, les objets de données sont appelés entités. Une entité est associée à une ou plusieurs propriétés nommées, chacune pouvant avoir une ou plusieurs valeurs. Les entités du même genre ne doivent pas nécessairement avoir les mêmes propriétés, et les valeurs d'une entité pour une propriété donnée ne doivent pas toutes être du même type de données. (Si nécessaire, une application peut établir et appliquer de telles restrictions dans son propre modèle de données.)

Le mode Datastore est compatible avec divers types de données pour les valeurs de propriété, parmi lesquels :

Entiers
Nombres à virgule flottante
Chaînes
Dates
Données binaires

Chaque entité de la base de données en mode Datastore possède une clé qui l'identifie de manière unique. Cette dernière comprend les composants suivants :

L'espace de noms de l'entité, qui permet de définir l'architecture mutualisée.
Le genre de l'entité, qui la classe dans une catégorie pour les besoins des requêtes.
Un identifiant associé à l'entité de manière individuelle, qui peut être :
- une chaîne de nom de clé ;
- un ID numérique sous forme d'entier.
un chemin d'ancêtre facultatif localisant l'entité dans la hiérarchie de la base de données.

Une application peut extraire une entité individuelle de la base de données à l'aide de la clé de l'entité, ou extraire une ou plusieurs entités en émettant une requête basée sur leurs clés ou leurs valeurs de propriété.

Cloud Firestore en mode Datastore lui-même n'applique aucune restriction à la structure des entités pour déterminer, par exemple, si une propriété donnée a une valeur d'un type particulier. Cette tâche revient à l'application.

Les extraits figurant sur cette page s'appuient sur l'exemple de la page Premiers pas avec Cloud Firestore en mode Datastore.

Utiliser des entités

Les applications peuvent utiliser l'API Cloud Firestore en mode Datastore pour créer, récupérer, mettre à jour et supprimer des entités. Si l'application connaît la clé complète d'une entité (ou si elle peut la déduire de sa clé parente, de son genre et de son identifiant), elle peut s'en servir pour effectuer des opérations directement sur l'entité. Une application peut également obtenir la clé d'une entité à la suite d'une requête. Pour plus d'informations, consultez la page Requêtes.

Créer une entité

Pour créer une entité, initialisez-la et définissez ses propriétés :

C#

Pour savoir comment installer et utiliser la bibliothèque cliente pour Cloud Datastore, consultez la page Bibliothèques clientes Cloud Datastore. Pour en savoir plus, consultez la documentation de référence de l'API Cloud Datastore en langage C#.

Pour vous authentifier auprès de Cloud Datastore, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement 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

Vous pouvez enregistrer l'entité dans la base de données à l'aide d'une opération upsert (qui écrase une entité si elle existe déjà dans le mode Datastore) ou d'une opération insert (la clé de l'entité ne doit pas déjà exister).

Voici comment effectuer une opération upsert sur une entité :

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

Voici comment effectuer une opération insert sur une entité :

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

Récupérer une entité

Pour extraire une entité de la base de données, effectuez une opération lookup à l'aide de sa clé :

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

Mettre à jour une entité

Pour effectuer une opération update sur une entité existante, modifiez les propriétés de l'entité précédemment récupérée et stockez-la à l'aide de la clé :

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

Les données fournies écrasent l'entité existante. L'objet entier doit être envoyé à la base de données. Si l'entité n'existe pas, la mise à jour échoue. Si vous souhaitez mettre à jour ou créer une entité, utilisez upsert comme décrit précédemment. L'utilisation d'une transaction vous permet d'effectuer les opérations get et update en une seule transaction atomique.

Supprimer une entité

En utilisant la clé d'une entité, vous pouvez supprimer l'entité à l'aide de la fonction delete :

C#

_db.Delete(_sampleTask.Key);

Go

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

Java

datastore.delete(taskKey);

Node.js

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

PHP

$datastore->delete($taskKey);

Python

from google.cloud import datastore

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

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

Ruby

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

Opérations par lot

Cloud Firestore en mode Datastore est compatible avec les versions par lot des opérations, qui lui permettent d'intervenir sur plusieurs objets via un seul appel en mode Datastore.

Il est plus rapide d'effectuer des appels par lot que des appels distincts pour chaque entité individuelle, car ils entraînent une surcharge pour un seul appel de service. Si plusieurs groupes d'entités sont impliqués, les opérations pour tous les groupes sont effectuées en parallèle côté serveur.

Par exemple, vous pouvez effectuer une opération upsert sur plusieurs entités :

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

Vous pouvez effectuer une opération lookup sur plusieurs entités :

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

Vous pouvez supprimer plusieurs entités :

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

Les opérations par lot ne modifient pas vos coûts de lecture, d'écriture ou de suppression, qui sont documentés sur la page Tarifs et quotas. Vous serez facturé pour chaque clé employée dans une opération en lot, que cette clé existe ou non.

La taille des entités impliquées dans une opération n'a pas d'incidence sur les coûts des opérations de lecture, d'écriture ou de suppression. Cependant, elle en a sur les coûts liés à la taille de l'espace de stockage.

Incrémentation et autres transformations de propriétés

Utilisez des transformations de propriété telles que increment pour effectuer des mises à jour côté serveur d'une propriété. Une transformation de propriété évite une opération de lecture supplémentaire côté client pour obtenir la valeur actuelle et évite un calcul côté client pour déterminer la nouvelle valeur.

Le mode Datastore accepte les transformations de propriétés suivantes :

increment
maximum
minimum
appendMissingElements
removeAllFromArray
setToServerValue(REQUEST_TIME)

L'exemple suivant illustre une transformation de propriété. Cette opération incrémente les propriétés des valeurs spécifiées :

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

L'exemple suivant définit une valeur de propriété sur l'heure à laquelle le serveur a traité la requête, avec une précision de l'ordre de la milliseconde.

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

L'exemple suivant ajoute des éléments de tableau s'ils sont manquants.

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

Types mixtes avec `maximum` et `minimum`

Les transformations de propriété maximum et minimum prennent en entrée un entier ou un double (nombre à virgule flottante). La valeur de la propriété cible peut également être un entier ou une valeur double.

Si la propriété n'est pas un entier ou un double, ou si elle n'existe pas, la transformation définit la propriété sur la valeur et le type d'entrée donnés. Si une opération maximum est appliquée alors que la propriété et la valeur d'entrée sont de types mixtes (c'est-à-dire que l'une est un entier et l'autre un double), la propriété prend le type de l'opérande le plus grand. Pour minimum, la propriété prend le type de l'opérande le plus petit.

Si les opérandes sont équivalents (par exemple, 3 et 3,0), la propriété ne change pas. 0, 0.0 et -0.0 sont tous égaux à zéro. La valeur maximum ou minimum d'une valeur stockée nulle et d'une valeur d'entrée nulle est toujours la valeur stockée. La valeur maximum ou minimum de toute valeur numérique et NaN est NaN.

Plusieurs mutations et `PropertyMask`

Les transformations de propriété sont appliquées de manière séquentielle après toute mutation supplémentaire dans la requête. Un PropertyMask limite les mutations insert, update et upsert aux propriétés spécifiées, mais ne limite pas les transformations de propriétés.

Par exemple, en commençant par l'entité suivante :

REST

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

La requête suivante met à jour a et b, puis applique une transformation de propriété à la propriété 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
          }
        }
      ]
    }
  ]
}

Le résultat est le suivant :

REST

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

Genres et identifiants

Chaque entité est d'un genre particulier, ce qui permet de la classer dans une catégorie pour les besoins des requêtes. Par exemple, une application de liste de tâches peut représenter chaque tâche à effectuer avec une entité du genre Task.

Tous les noms de genre commençant par deux traits de soulignement (__) sont réservés et ne peuvent pas être employés.

Attribuer des identifiants

En plus d'un genre, chaque entité possède un identifiant, qui lui est attribué au moment de sa création. Comme il fait partie de la clé de l'entité, l'identifiant est associé de manière permanente à celle-ci et ne peut pas être modifié. Il peut être attribué de deux manières :

L'application peut spécifier sa propre chaîne de nom de clé pour l'entité.

Pour en savoir plus sur la taille maximale de la chaîne de clé d'entité, consultez Limites.
Cloud Firestore en mode Datastore peut attribuer automatiquement à l'entité un ID numérique sous forme d'entier.
Pour connaître les bonnes pratiques concernant l'attribution d'identifiants, consultez la section "Clés" des bonnes pratiques.

L'exemple suivant crée une clé de genre Task qui utilise un nom de clé, "sampleTask", comme identifiant :

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

Le mode Datastore peut également attribuer automatiquement des ID. Le mode Datastore génère une séquence aléatoire d'ID inutilisés distribués de manière approximativement uniforme. Chaque ID peut comporter jusqu'à 16 chiffres décimaux.

L'exemple suivant permet de créer une clé du genre Task, sans employer de nom de clé. Lorsqu'une entité avec une clé incomplète est enregistrée dans le mode Datastore, sa clé complète (y compris l'ID attribué automatiquement) est renvoyée :

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"

Si vous souhaitez que les ID d'entité soient visibles par l'utilisateur et/ou si vous souhaitez les afficher en fonction de leur ordre, l'allocation manuelle est la meilleure solution.

Attribuer votre propre ID numérique

Au lieu d'employer des chaînes de nom de clé ou de générer automatiquement des ID numériques, les applications avancées peuvent parfois attribuer manuellement leurs propres ID numériques aux entités créées. Sachez toutefois que rien n'empêche une base de données en mode Datastore d'attribuer l'un de vos ID numériques manuels à une autre entité. Le seul moyen d'éviter de tels conflits est que votre application obtienne un bloc d'ID avec la méthode allocateIds().

Le générateur automatique d'ID du mode Datastore effectue un suivi des ID alloués avec ces méthodes et évite de les réutiliser pour une autre entité. Vous pouvez ainsi employer ces ID sans que cela ne génère de conflit. Vous ne pouvez pas choisir manuellement les valeurs renvoyées par la méthode allocateIds(). Les valeurs renvoyées par allocateIds() sont attribuées par le mode Datastore.

Chemins d'ancêtre

Dans une base de données en mode Datastore, les entités forment un espace structuré de manière hiérarchique, semblable à la structure de répertoires d'un système de fichiers. Lorsque vous créez une entité, vous pouvez éventuellement en désigner une autre comme son parent. La nouvelle entité est alors un enfant de l'entité parente. Contrairement à ce qui se produit dans un système de fichiers, l'entité parente n'a pas besoin d'exister réellement. Une entité sans parent est une entité racine. L'association entre une entité et son parent est permanente, et elle ne peut plus être modifiée une fois l'entité créée. Le mode Datastore n'attribue jamais le même ID numérique à deux entités ayant le même parent ni à deux entités racines (celles sans parent).

Une entité peut avoir plusieurs niveaux d'ancêtres et de descendants. Le parent d'une entité, le parent de son parent, etc. sont ses ancêtres. Ses enfants, les enfants de ses enfants, etc. sont ses descendants. La séquence d'entités commençant par une entité racine et allant du parent à l'enfant, menant à une entité donnée, constitue le chemin d'ancêtre de cette entité. La clé complète identifiant l'entité se compose d'une séquence de paires genre-identifiant spécifiant son chemin d'ancêtre et se terminant par celles de l'entité elle-même :

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

Pour une entité racine, le chemin d'ancêtre est vide, et la clé est constituée uniquement du genre et de l'identifiant de l'entité :

[User:alice]

Niveaux de parents

Organisez les données à l'aide des niveaux de parents. Par exemple, si l'application organise les entités Task par entités TaskList, utilisez un niveau de parent :

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

Si l'application organise les entités Task d'abord par entités User, puis par entités TaskList, utilisez plusieurs niveaux de parents :

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]
                         ])

Comme indiqué dans l'exemple précédent, lorsque vous créez une entité avec un parent, vous spécifiez le chemin d'accès complet de l'ancêtre du parent.

Une application qui gère des profils utilisateur peut ne nécessiter qu'un seul niveau de parent pour les données de ces profils. Par exemple, employez un chemin d'ancêtre à un seul niveau (User) pour les entités Profile :

[User:alice, Profile:public]

Une application gérant les réservations de salles de conférence peut nécessiter plusieurs niveaux de parents, par exemple un chemin d'ancêtre à plusieurs niveaux (Building/Floor) pour les entités Room :

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

Groupes d'entités

Un groupe d'entités comprend une entité racine et tous ses descendants. Les applications s'en servent généralement pour organiser des données étroitement liées. Par exemple, une application peut utiliser un groupe d'entités pour stocker des données sur un produit ou un profil utilisateur.

Propriétés et types de valeurs

Les valeurs de données associées à une entité consistent en une ou plusieurs propriétés. Chaque propriété a un nom, et une ou plusieurs valeurs.

Une propriété peut avoir des valeurs de plus d'un type, et deux entités peuvent avoir des valeurs de types différents pour la même propriété. Une propriété peut être indexée ou non indexée (les requêtes qui trient ou filtrent en fonction d'une propriété p vont ignorer les entités où cette propriété p est non indexée).

Voici des exemples de propriétés :

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

Propriétés de tableau

Une propriété comportant plus d'une valeur est appelée propriété de tableau. Cet exemple contient deux propriétés de tableau. La première, nommée tags, possède les valeurs fun et programming. La seconde, qui se nomme collaborators, comporte les valeurs alice et 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

Les propriétés de tableau peuvent être utiles, par exemple, lors de l'exécution de requêtes avec des filtres d'égalité : une entité satisfait à la requête si l'une de ses valeurs de propriété correspond à la valeur spécifiée dans le filtre. Pour en savoir plus sur les propriétés de tableau, y compris sur les problèmes dont vous devez avoir connaissance, consultez la page Requêtes.

Types de valeurs acceptés

Les propriétés sont stockées sous forme de mappage string/value contenant les noms et les valeurs des propriétés de l'entité. Les types suivants sont acceptés pour les valeurs :

Entier 32 bits

API REST
- Nom du champ : entityValue
- type : mappage d'entité JSON contenant une seule propriété __int__ avec un entier integerValue
API RPC
- Nom du champ : entity_value
- type : un message Entity contenant une seule propriété __int__ avec un integer_value
Ordre de tri : numérique

Entier 64 bits

API REST
- Nom du champ : integerValue
- Type : nombre ou chaîne. Utilisez des chaînes pour les entiers qui ne peuvent pas être représentés exactement par des nombres.
API RPC
- Nom du champ : integer_value
- Type : int64
Ordre de tri : numérique

Tableau

API REST
- Nom du champ : arrayValue
- Type : un objet ArrayValue qui contient un tableau d'objets de valeur JSON
- Une propriété de tableau peut être attribuée à l'aide du champ arrayValue, qui est de type ArrayValue, et en définissant son champ values sur un tableau de valeurs. Pour qu'une propriété ne soit pas indexée, définissez le champ excludeFromIndexes de l'objet de valeur de la propriété sur true.
API RPC
- Nom du champ : array_value
- Type : un message ArrayValue contenant un ou plusieurs messages Value
- Vous pouvez affecter une propriété de tableau en utilisant le champ array_value, qui est du type ArrayValue, et en renseignant son champ values à l'aide de plusieurs objets Value. Pour qu'une propriété ne soit pas indexée, définissez le champ exclude_from_indexes de Value sur true.
Ordre de tri : aucun
Remarques : Ce type ne peut pas contenir une autre valeur de tableau. L'instance de valeur ne doit pas définir meaning ou exclude_from_indexes.

Booléen

API REST
- Nom du champ : booleanValue
- Type : true ou false
API RPC
- Nom du champ : boolean_value
- Type : bool
Ordre de tri : false < true

Code temporel BSON

API REST
- Nom du champ : entityValue
- type : mappage d'entités JSON contenant une propriété __request_timestamp__ avec les propriétés d'entier seconds et increment
API RPC
- Nom du champ : entity_value
- type : message Entity représentant un code temporel BSON contenant seconds et increment
Ordre de tri : chronologique
Remarques : Valeur de code temporel de 64 bits comprenant des secondes Unix et un compteur d'incrémentation.

Octets (blob)

API REST
- Nom du champ : blobValue
- Type : chaîne. Doit être encodé en base64.
API RPC
- Nom du champ : blob_value
- Type : bytes
Ordre de tri : ordre des octets
Remarques : Jusqu'à 1 500 octets si la propriété est indexée. Sinon, jusqu'à 1 048 487 octets (1 Mio – 89 octets).

Octets avec sous-type

API REST
- Nom du champ : entityValue
- type : mappage d'entités JSON contenant une seule propriété __binary__ avec blobValue encodé en base64 (octet de sous-type ajouté aux données)
API RPC
- Nom du champ : entity_value
- type : un message Entity contenant une seule propriété __binary__ avec blob_value (sous-type d'octet ajouté aux données)
Ordre de tri : ordre des octets (sous-type, puis valeur)
Remarques : Séquence d'octets binaires avec un indicateur de sous-type BSON.

Date et heure (code temporel)

API REST
- Nom du champ : timestampValue
- Type : chaîne (au format RFC 3339, avec une précision de l'ordre de la milliseconde, par exemple 2013-05-14T00:01:00.234Z)
API RPC
- Nom du champ : timestamp_value
- Type : Timestamp
Ordre de tri : chronologique
Remarques :
- En cas de stockage dans le mode Datastore, limitez la précision aux microsecondes. Toute précision supplémentaire est arrondie.
- Lorsque ce type est renvoyé dans une requête de projection, le mode Datastore convertit les valeurs d'horodatage en valeurs entières, exprimées en microsecondes.

Decimal128

API REST
- Nom du champ : entityValue
- type : mappage d'entités JSON contenant une seule propriété __decimal128__ avec un stringValue
API RPC
- Nom du champ : entity_value
- type : un message Entity contenant une seule propriété __decimal128__ avec un string_value
Ordre de tri : numérique
Remarques : Nombre à virgule flottante décimal de 128 bits pour l'arithmétique de haute précision.

Double (nombre à virgule flottante)

API REST
- Nom du champ : doubleValue
- Type : nombre
API RPC
- Nom du champ : double_value
- Type : double
Ordre de tri : numérique
Remarques : Format double précision 64 bits (IEEE 754)

Entité intégrée

API REST
- Nom du champ : entityValue
- Type : une entité JSON
API RPC
- Nom du champ : entity_value
- Type : un message Entity
Ordre de tri : aucun
Remarques : En cas d'indexation, vous pouvez exécuter une requête sur des sous-propriétés. Si vous excluez cette valeur de l'indexation, toutes les sous-propriétés en sont également exclues.

Point géographique

API REST
- Nom du champ : geoPointValue
- Type : une paire latitude/longitude JSON
API RPC
- Nom du champ : geo_point_value
- Type : un message LatLng
Ordre de tri : par latitude, puis par longitude

Clé

API REST
- Nom du champ : keyValue
- Type : une clé du mode Datastore JSON
API RPC
- Nom du champ : key_value
- Type : un message Key
Ordre de tri : par éléments de chemin (genre, identifiant, genre, identifiant, etc.)

MaxKey

API REST
- Nom du champ : entityValue
- type : mappage d'entités JSON contenant une seule propriété __max__ avec un nullValue
API RPC
- Nom du champ : entity_value
- type : un message Entity contenant une seule propriété __max__ avec un null_value

MinKey

API REST
- Nom du champ : entityValue
- type : mappage d'entités JSON contenant une seule propriété __min__ avec un nullValue
API RPC
- Nom du champ : entity_value
- type : un message Entity contenant une seule propriété __min__ avec un null_value

Vide

API REST
- Nom du champ : nullValue
- Type : Null
API RPC
- Nom du champ : null_value
- Type : NullValue
Ordre de tri : aucun

ObjectId

API REST
- Nom du champ : entityValue
- type : mappage d'entités JSON contenant une seule propriété __oid__ avec une valeur stringValue (chaîne hexadécimale en minuscules)
API RPC
- Nom du champ : entity_value
- type : un message Entity contenant une seule propriété __oid__ avec un string_value
Ordre de tri : par séquence de 12 octets

Expression régulière

API REST
- Nom du champ : entityValue
- type : mappage d'entités JSON contenant __regex__ avec des propriétés pour pattern et options
API RPC
- Nom du champ : entity_value
- type : message Entity représentant une expression régulière avec les propriétés pattern et options
Ordre de tri : par motif, puis par options

Chaîne de texte

API REST
- Nom du champ : stringValue
- type : chaîne
API RPC
- Nom du champ : string_value
- Type : string
Ordre de tri : ordre des octets encodés en UTF-8
Remarques : Jusqu'à 1 500 octets si la propriété est indexée. Sinon, jusqu'à 1 048 487 octets (1 Mio – 89 octets).

Ordre des types de valeurs

Lorsqu'une requête implique une propriété avec des valeurs de différents types, une base de données en mode Datastore emploie un ordre déterministe basé sur les représentations internes. La liste suivante indique l'ordre appliqué :

Valeurs Null
MinKey
Entiers 32 bits
Entiers 64 bits et codes temporels
Valeurs booléennes
Chaînes d'octets et chaînes Unicode
Octets avec sous-types
Doubles (NaN trié en dernier)
Points géographiques
Clés du mode Datastore
ObjectId
Code temporel BSON
Expression régulière
Decimal128 (NaN trié en dernier)
MaxKey

Entités, propriétés et clés Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Utiliser des entités

Créer une entité

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

Récupérer une entité

C#

Go

Java

Node.js

PHP

Python

Ruby

Mettre à jour une entité

C#

Go

Java

Node.js

PHP

Python

Ruby

Supprimer une entité

C#

Go

Java

Node.js

PHP

Python

Ruby

Opérations par lot

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

Incrémentation et autres transformations de propriétés

REST

REST

REST

Types mixtes avec maximum et minimum

Plusieurs mutations et PropertyMask

REST

REST

Genres et identifiants

Attribuer des identifiants

Entités, propriétés et clés

Types mixtes avec `maximum` et `minimum`

Plusieurs mutations et `PropertyMask`