Cette page a été traduite par l'API Cloud Translation.

Structurer des données pour renforcer la cohérence

Pour garantir la haute disponibilité, l'évolutivité et la durabilité, Datastore distribue les données sur de nombreuses machines et met en œuvre une réplication synchrone sans maître sur une vaste zone géographique. Cette conception implique cependant une concession : le débit en écriture d'un groupe d'entités donné est limité à environ un commit par seconde. Des limites s'appliquent également aux requêtes ou aux transactions couvrant plusieurs groupes d'entités. Cette page décrit plus en détail ces limites et indique les bonnes pratiques à suivre pour structurer les données, afin de garantir une cohérence forte tout en respectant les exigences de débit en écriture de l'application.

Niveaux de cohérence

Les requêtes Datastore peuvent produire des résultats à l'un des deux niveaux de cohérence suivants :

Les requêtes fortement cohérentes garantissent les résultats les plus à jour, mais leur exécution peut prendre plus de temps et elles peuvent ne pas être acceptées dans certains cas.
Les requêtes cohérentes à terme s'exécutent en règle générale plus rapidement, mais elles peuvent parfois renvoyer des résultats obsolètes.

Dans les requêtes cohérentes à terme, les index servant à la collecte des résultats sont également accessibles avec une cohérence à terme. Par conséquent, ces requêtes peuvent parfois renvoyer des entités qui ne répondent plus à leurs critères, mais aussi omettre des entités qui y répondent. Les requêtes fortement cohérentes sont cohérentes de manière transactionnelle, ce qui signifie que les résultats reposent sur un seul instantané cohérent des données.

Garanties en matière de cohérence

En fonction de leur nature, les requêtes renvoient leurs résultats avec différents niveaux de garantie de cohérence :

Les requêtes ascendantes (qui s'exécutent sur un groupe d'entités) sont fortement cohérentes par défaut, mais vous pouvez les rendre cohérentes à terme en définissant les règles de lecture Datastore (voir ci-dessous).
Les requêtes globales (celles qui ne s'exécutent pas sur un groupe d'entités) sont toujours cohérentes à terme.

Dans de nombreuses applications, il est acceptable de recourir à la cohérence à terme (à savoir à une requête globale couvrant plusieurs groupes d'entités et pouvant parfois renvoyer des données légèrement obsolètes) lors de l'obtention d'une vue d'ensemble de données non liées, puis de passer à la cohérence forte (requête ascendante ou recherche d'une seule entité) lors de la visualisation ou de la modification d'un seul ensemble de données étroitement liées. Dans ces applications, il est généralement judicieux de placer les données étroitement liées dans des groupes d'entités. Un nombre élevé de groupes d'entités augmente le débit, tandis qu'un nombre moins important de groupes d'entités augmente le volume d'entités pouvant être lues dans une seule requête ascendante. Une application doit en tenir compte pour déterminer le juste équilibre entre débit et cohérence.

Règles de lecture Datastore

Pour améliorer les performances, vous pouvez définir les règles de lecture d'une requête afin que les résultats soient cohérents à terme. (L'API Datastore vous permet également de définir explicitement des règles de cohérence forte, mais ce paramétrage n'a aucun effet en pratique, car les requêtes globales sont toujours cohérentes à terme, quelles que soient les règles.)

Vous pouvez activer les lectures cohérentes à terme via les options de lecture de l'objet de requête :

C#

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

Pour vous authentifier auprès de Cloud Datastore, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

Query query = new Query("Task")
{
    Filter = Filter.HasAncestor(_db.CreateKeyFactory("TaskList")
        .CreateKey(keyName))
};
var results = _db.RunQuery(query,
    ReadOptions.Types.ReadConsistency.Eventual);

Go

Pour savoir comment installer et utiliser la bibliothèque cliente pour Cloud Datastore, consultez Bibliothèques clientes Cloud Datastore. Pour en savoir plus, consultez les API Go Cloud Datastore documentation de référence.

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.

ancestor := datastore.NameKey("TaskList", "default", nil)
query := datastore.NewQuery("Task").Ancestor(ancestor).EventualConsistency()

Java

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 Java.

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(
            PropertyFilter.hasAncestor(
                datastore.newKeyFactory().setKind("TaskList").newKey("default")))
        .build();
datastore.run(query, ReadOption.eventualConsistency());

Node.js

const ancestorKey = datastore.key(['TaskList', 'default']);
const query = datastore.createQuery('Task').hasAncestor(ancestorKey);

query.run({consistency: 'eventual'});

PHP

$query = $datastore->query()
    ->kind('Task')
    ->hasAncestor($datastore->key('TaskList', 'default'));
$result = $datastore->runQuery($query, ['readConsistency' => 'EVENTUAL']);

Python

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 les API Python Cloud Datastore documentation de référence.

from google.cloud import datastore

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

query = client.query(kind="Task")
query.fetch(eventual=True)

Ruby

# task_list_name = "default"
ancestor_key = datastore.key "TaskList", task_list_name

query = datastore.query("Task")
                 .ancestor(ancestor_key)

tasks = datastore.run query, consistency: :eventual

Transactions et considérations en matière de cohérence

Les commits Datastore sont soit transactionnels (ils surviennent dans le contexte d'une transaction et l'ensemble de mutations de cette dernière est appliqué en totalité ou n'est pas appliqué du tout), soit non transactionnels (l'ensemble de mutations peut s'appliquer partiellement).

Une seule transaction peut inclure zéro, une ou plusieurs mutations de création, de mise à jour ou de suppression. Pour maintenir la cohérence des données, la transaction garantit que toutes les mutations qu'elle contient sont appliquées à Datastore en tant qu'unité ou, en cas d'échec de l'une de ces mutations, qu'aucune d'entre elles n'est appliquée. En outre, toutes les lectures fortement cohérentes (requêtes ascendantes ou opérations lookup) effectuées dans la même transaction reposent sur un seul instantané cohérent des données. Les requêtes fortement cohérentes doivent spécifier un filtre d'ancêtre. Les requêtes qui participent à une transaction sont toujours fortement cohérentes. Les transactions peuvent impliquer jusqu'à 25 groupes d'entités. Les lectures cohérentes à terme ne sont pas soumises à ces limites et conviennent dans de nombreux cas. Avec des lectures cohérentes à terme, vous pouvez répartir les données entre un plus grand nombre de groupes d'entités, ce qui vous permet d'obtenir un meilleur débit en écriture en exécutant des commits en parallèle sur les différents groupes d'entités. Cependant, vous devez connaître les caractéristiques des lectures cohérentes à terme afin de déterminer si elles sont adaptées à votre application :

Les résultats de ces lectures peuvent ne pas refléter les dernières transactions. Cela peut se produire, car ces lectures ne garantissent pas que l'instance dupliquée sur laquelle elles s'exécutent est à jour. À la place, elles utilisent les données disponibles sur cette instance dupliquée au moment de l'exécution de la requête, quelles qu'elles soient.
Une transaction ayant fait l'objet d'un commit et qui couvre plusieurs groupes d'entités peut sembler avoir été appliquée à certaines entités et non à d'autres. Sachez cependant qu'une transaction ne semblera jamais avoir été partiellement appliquée au sein d'une seule entité.
Les résultats de la requête peuvent inclure des entités qui n'auraient pas dû l'être selon les critères de filtrage, et peuvent exclure des entités qui auraient dû être incluses. Cela peut se produire, car la version d'instantané employée pour lire les index peut différer de celle ayant servi à lire l'entité.

Structurer les données à des fins de cohérence

Pour comprendre comment structurer les données de façon à assurer une cohérence forte, nous allons comparer deux approches différentes pour une application simple de liste de tâches. La première approche crée chaque entité dans son propre nouveau groupe d'entités (c'est-à-dire que chaque entité est une entité racine) :

C#

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

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 les API Node.js Cloud Datastore documentation de référence.

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

Une requête est ensuite exécutée sur le genre d'entité Task pour récupérer les tâches qui ne sont pas encore terminées et dont la priorité est supérieure ou égale à 4, en les triant par ordre décroissant de priorité :

C#

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.Equal("done", false),
        Filter.GreaterThanOrEqual("priority", 4)),
    Order = { { "priority", PropertyOrder.Types.Direction.Descending } }
};

Go

query := datastore.NewQuery("Task").
	FilterField("Done", "=", false).
	FilterField("Priority", ">=", 4).
	Order("-Priority")

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(
            CompositeFilter.and(
                PropertyFilter.eq("done", false), PropertyFilter.ge("priority", 4)))
        .setOrderBy(OrderBy.desc("priority"))
        .build();

Node.js

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 les API Node.js Cloud Datastore documentation de référence.

const query = datastore
  .createQuery('Task')
  .filter(
    and([
      new PropertyFilter('done', '=', false),
      new PropertyFilter('priority', '>=', 4),
    ])
  )
  .order('priority', {
    descending: true,
  });

PHP

$query = $datastore->query()
    ->kind('Task')
    ->filter('done', '=', false)
    ->filter('priority', '>=', 4)
    ->order('priority', Query::ORDER_DESCENDING);

Python

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 les API Python Cloud Datastore documentation de référence.

from google.cloud import datastore

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

query = client.query(kind="Task")
query.add_filter(filter=datastore.query.PropertyFilter("done", "=", False))
query.add_filter(filter=datastore.query.PropertyFilter("priority", ">=", 4))
query.order = ["-priority"]

Ruby

query = datastore.query("Task")
                 .where("done", "=", false)
                 .where("priority", ">=", 4)
                 .order("priority", :desc)

Cependant, étant donné que nous employons une requête cohérente à terme (plutôt qu'une requête ascendante), ses résultats peuvent ne pas contenir la nouvelle entité. Néanmoins, presque toutes les écritures sont disponibles pour des requêtes cohérentes à terme peu de temps après un commit. Pour de nombreuses applications, une solution fournissant les résultats d'une requête cohérente à terme dans le contexte des modifications de l'utilisateur actuel sera généralement suffisante pour rendre de telles latences parfaitement acceptables.

Pour obtenir une cohérence forte, la meilleure approche consiste à créer les entités avec un chemin d'ancêtre. Ce dernier identifie l'entité racine commune dans laquelle les entités créées sont regroupées. Cet exemple utilise un chemin d'ancêtre du genre TaskList nommé default :

C#

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

Go

parentKey := datastore.NameKey("TaskList", "default", nil)
key := datastore.IncompleteKey("Task", parentKey)

task := Task{
	Category:    "Personal",
	Done:        false,
	Priority:    4,
	Description: "Learn Cloud Datastore",
}

// A complete key is assigned to the entity when it is Put.
var err error
key, err = client.Put(ctx, key, &task)

Java

Key taskKey =
    datastore
        .newKeyFactory()
        .addAncestors(PathElement.of("TaskList", "default"))
        .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 taskKey = datastore.key([
  'TaskList',
  'default',
  'Task',
  'sampleTask',
]);

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

PHP

$parentKey = $datastore->key('TaskList', 'default');
$key = $datastore->key('Task')->ancestorKey($parentKey);
$task = $datastore->entity(
    $key,
    [
        'Category' => 'Personal',
        'Done' => false,
        'Priority' => 4,
        'Description' => 'Learn Cloud Datastore'
    ]
);

Python

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 les API Python Cloud Datastore documentation de référence.

from google.cloud import datastore

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

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

task = datastore.Entity(key=key_with_parent)

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

Ruby

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

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

Vous pourrez ensuite exécuter une requête ascendante fortement cohérente au sein du groupe d'entités identifié par l'entité racine commune :

C#

Query query = new Query("Task")
{
    Filter = Filter.HasAncestor(_db.CreateKeyFactory("TaskList")
        .CreateKey(keyName))
};

Go

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 les API Go Cloud Datastore documentation de référence.

ancestor := datastore.NameKey("TaskList", "default", nil)
query := datastore.NewQuery("Task").Ancestor(ancestor)

Java

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 les API Java Cloud Datastore documentation de référence.

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(
            PropertyFilter.hasAncestor(
                datastore.newKeyFactory().setKind("TaskList").newKey("default")))
        .build();

Node.js

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 les API Node.js Cloud Datastore documentation de référence.

const ancestorKey = datastore.key(['TaskList', 'default']);

const query = datastore.createQuery('Task').hasAncestor(ancestorKey);

PHP

$ancestorKey = $datastore->key('TaskList', 'default');
$query = $datastore->query()
    ->kind('Task')
    ->hasAncestor($ancestorKey);

Python

from google.cloud import datastore

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

# Query filters are omitted in this example as any ancestor queries with a
# non-key filter require a composite index.
ancestor = client.key("TaskList", "default")
query = client.query(kind="Task", ancestor=ancestor)

Ruby

# task_list_name = "default"
ancestor_key = datastore.key "TaskList", task_list_name

query = datastore.query("Task")
                 .ancestor(ancestor_key)

Cette approche assure une cohérence forte en effectuant les opérations d'écriture dans un seul groupe d'entités par liste de tâches, mais elle limite également les modifications apportées à la liste de tâches à une écriture par seconde (limite acceptée pour les groupes d'entités). Si le nombre d'écritures est susceptible d'être plus élevé dans votre application, vous devrez peut-être envisager de recourir à d'autres moyens. Par exemple, si l'application est un livre d'or permettant aux utilisateurs de poster des messages sur une page publique, vous pouvez placer les publications récentes dans Memcache avec une date d'expiration, et afficher une combinaison de publications récentes issues de Memcache et de Datastore. Ou bien vous pouvez les mettre en cache dans un cookie, indiquer un état dans l'URL, ou tout autre chose encore. L'objectif est de trouver une solution de mise en cache fournissant les données de l'utilisateur actuel au cours de la période pendant laquelle celui-ci publie sur l'application. N'oubliez pas que si vous effectuez une opération lookup, une requête ascendante (en supposant que les règles de lecture ne sont pas définies pour être cohérentes à terme) ou toute opération dans une transaction, vous verrez toujours les données écrites le plus récemment.

Pour obtenir d'autres exemples d'utilisation des transactions, cliquez ici.

Limites des groupes d'entités en matière de transactions

L'organisation des données en groupes d'entités peut limiter le nombre de transactions pouvant être effectuées :

Toutes les données auxquelles accède une transaction doivent être contenues dans 25 groupes d'entités au maximum.
Si vous souhaitez utiliser des requêtes dans une transaction, les données doivent être organisées en groupes d'entités de sorte que vous puissiez spécifier des filtres d'ancêtres qui correspondent aux bonnes données.
Le débit en écriture est limité à environ une transaction par seconde pour un seul groupe d'entités. Cette limite a été définie car Datastore effectue une réplication synchrone sans maître de chaque groupe d'entités sur une vaste zone géographique, afin de fournir une fiabilité et une tolérance aux pannes élevées.

Pour plus d'informations sur la mise à jour des entités et des index, consultez l'article Isolation de transaction.