Tous les produits
Search
Centre de documentation

Tablestore:Write data

Dernière mise à jour :Aug 31, 2026

Tablestore propose trois opérations pour écrire des données dans les tables : PutRow, UpdateRow et BatchWriteRow.

Remarque

Les lignes constituent les unités de base des tables. Chaque ligne se compose de colonnes de clé primaire et de colonnes d'attribut facultatives. Les noms et les types des colonnes de clé primaire sont identiques pour toutes les lignes d'une table. En revanche, les colonnes d'attribut peuvent varier d'une ligne à l'autre. Pour plus d'informations, consultez la rubrique Présentation.

Opérations

Opération Portée Comportement
PutRow Ligne unique Insère une ligne. Si une ligne possédant la même clé primaire existe déjà, cette opération supprime toutes les versions des données dans toutes les colonnes, puis écrit les nouvelles données.
UpdateRow Ligne unique Ajoute, met à jour ou supprime des colonnes d'attribut. Supprime une version spécifique des données d'une colonne. Si la ligne n'existe pas, une nouvelle ligne est insérée (sauf si la demande ne contient que des suppressions de colonnes).
BatchWriteRow Plusieurs lignes Combine plusieurs sous-opérations PutRow, UpdateRow et DeleteRow en une seule demande, portant sur une ou plusieurs tables. Chaque sous-opération est exécutée et fait l'objet d'une réponse indépendante.

Paramètres communs

Avant d'écrire des données, vous pouvez configurer les paramètres facultatifs suivants pour toute opération d'écriture :

  • Numéro de version des données : Par défaut, Tablestore utilise l'horodatage UNIX actuel (millisecondes écoulées depuis le January 1, 1970, 00:00:00 UTC) comme numéro de version. Spécifiez un numéro de version personnalisé si nécessaire. Pour plus d'informations, consultez la rubrique Versions des données et TTL.

  • Mise à jour conditionnelle : Définissez une condition d'existence de ligne ou une condition basée sur les valeurs des colonnes. Pour plus d'informations, consultez la rubrique Mises à jour conditionnelles.

Réponse de l'opération PutRow

  • En cas de succès, Tablestore renvoie le nombre d'unités de capacité (CU) consommées.

  • En cas d'échec, Tablestore renvoie un code d'erreur (par exemple, échec de la validation des paramètres, volume excessif de données de ligne ou échec de la vérification de l'existence de la ligne).

Remarque

Pour plus d'informations sur les codes d'erreur, consultez la rubrique Codes d'erreur.

Gestion des échecs partiels avec BatchWriteRow

Lorsque certaines lignes échouent lors d'une demande BatchWriteRow, Tablestore ne lève pas d'exception. À la place, il renvoie une réponse BatchWriteRowResponse contenant des informations sur les lignes ayant échoué. Appelez toujours la méthode isAllSucceed pour vérifier si toutes les lignes ont été écrites avec succès.

Si le serveur détecte des paramètres invalides dans certaines opérations, il peut renvoyer une erreur avant d'exécuter toute opération incluse dans la demande.

BatchWriteRow prend également en charge les conditions par opération : configurez séparément les conditions de mise à jour pour chaque sous-opération PutRow, UpdateRow ou DeleteRow.

Utiliser la console Tablestore

La console Tablestore permet d'insérer et de mettre à jour une seule ligne de données.

  1. Connectez-vous à la console Tablestore.

  2. Sur la page Overview, repérez l'instance cible et cliquez sur Manage Instance dans la colonne Actions.

  3. Dans l'onglet Tables de l'onglet Instance Details, cliquez sur le nom de la table cible.

  4. Dans l'onglet Query Data de la page de gestion de la table, insérez ou mettez à jour les données.

Insertion d'une seule ligne

  1. Cliquez sur Insert.

  2. Dans la boîte de dialogue Insert, saisissez les valeurs dans la colonne Primary Key Value.

  3. Cliquez sur l'icône image et configurez les paramètres Name, Type, Value et Version. Pour ajouter plusieurs colonnes d'attribut, cliquez à chaque fois sur l'icône image afin d'ajouter une colonne et de configurer ses paramètres.

  4. Cliquez sur OK.

Mise à jour d'une seule ligne

  1. Sélectionnez la ligne à mettre à jour et cliquez sur Update.

  2. Dans la boîte de dialogue Update, modifiez les colonnes d'attribut :

    • Ajouter une colonne : Cliquez sur l'icône image et configurez les paramètres.

    • Supprimer une colonne : Sélectionnez Delete All dans la liste déroulante Actions.

    • Supprimer une version spécifique : Sélectionnez Delete dans la liste déroulante Actions et sélectionnez le numéro de version à supprimer.

    • Mettre à jour une valeur : Sélectionnez Update dans la liste déroulante Actions et modifiez la valeur.

  3. Cliquez sur OK.

Utiliser la CLI Tablestore

Insérer une ligne

Exécutez la commande put. Pour plus d'informations, consultez la rubrique Insérer des données.

L'exemple suivant insère une ligne dont la première colonne de clé primaire est 86 et la seconde colonne de clé primaire est 6771. La ligne comporte deux colonnes d'attribut de type STRING : name et country.

put --pk '["86", 6771]' --attr '[{"c":"name", "v":"redchen"}, {"c":"country", "v":"china"}]'

Mettre à jour une ligne

Exécutez la commande update. Pour plus d'informations, consultez la rubrique Mettre à jour des données.

L'exemple suivant met à jour la ligne dont la première colonne de clé primaire est 86 et la seconde colonne de clé primaire est 6771. L'indicateur --condition ignore insère les données indépendamment de l'existence de la ligne. Si la ligne existe déjà, les nouvelles données écrasent les données existantes.

update --pk '["86", 6771]' --attr '[{"c":"name", "v":"redchen"}, {"c":"country", "v":"china"}]' --condition ignore

Utiliser les SDK Tablestore

Écrivez des données à l'aide de l'un des SDK suivants : SDK Tablestore pour Java, SDK Tablestore pour Go, SDK Tablestore pour Python, SDK Tablestore pour Node.js, SDK Tablestore pour .NET ou SDK Tablestore pour PHP.

Les exemples ci-dessous utilisent le SDK Java.

Insérer une seule ligne

La méthode PutRow prend en charge les numéros de version générés par le système, les numéros de version personnalisés et les écritures conditionnelles.

Numéro de version généré par le système

Insérez une ligne comportant 10 colonnes d'attributs, chacune stockant une version des données. Le système génère automatiquement les numéros de version.

private static void putRow(SyncClient client, String pkValue) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the table.
    RowPutChange rowPutChange = new RowPutChange("<TABLE_NAME>", primaryKey);

    // Add attribute columns.
    for (int i = 0; i < 10; i++) {
        rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(i)));
    }

    client.putRow(new PutRowRequest(rowPutChange));
}

Numéro de version personnalisé

Insérez une ligne comportant 10 colonnes d'attributs, chacune stockant trois versions de données avec des numéros de version personnalisés.

private static void putRow(SyncClient client, String pkValue) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the table.
    RowPutChange rowPutChange = new RowPutChange("<TABLE_NAME>", primaryKey);

    // Add attribute columns.
    long ts = System.currentTimeMillis();
    for (int i = 0; i < 10; i++) {
        for (int j = 0; j < 3; j++) {
            rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(j), ts + j));
        }
    }

    client.putRow(new PutRowRequest(rowPutChange));
}

Condition d'existence de la ligne

Insérez une ligne comportant 10 colonnes d'attributs (trois versions chacune) uniquement si la ligne spécifiée n'existe pas.

private static void putRow(SyncClient client, String pkValue) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the table.
    RowPutChange rowPutChange = new RowPutChange("<TABLE_NAME>", primaryKey);

    // Specify a row existence condition that expects the specified row to not exist.
    rowPutChange.setCondition(new Condition(RowExistenceExpectation.EXPECT_NOT_EXIST));

    // Add attribute columns.
    long ts = System.currentTimeMillis();
    for (int i = 0; i < 10; i++) {
        for (int j = 0; j < 3; j++) {
            rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(j), ts + j));
        }
    }

    client.putRow(new PutRowRequest(rowPutChange));
}

Conditions d'existence de la ligne et de valeur de colonne

Insérez une ligne comportant 10 colonnes d'attributs (trois versions chacune) lorsque la ligne existe et que la valeur de Col0 est supérieure à 100.

private static void putRow(SyncClient client, String pkValue) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the table.
    RowPutChange rowPutChange = new RowPutChange("<TABLE_NAME>", primaryKey);

    // Specify a row existence condition and a column-based condition that expect the specified row to exist and the value of the Col0 column to be greater than 100.
    Condition condition = new Condition(RowExistenceExpectation.EXPECT_EXIST);
    condition.setColumnCondition(new SingleColumnValueCondition("Col0",
            SingleColumnValueCondition.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100)));
    rowPutChange.setCondition(condition);

    // Add attribute columns.
    long ts = System.currentTimeMillis();
    for (int i = 0; i < 10; i++) {
        for (int j = 0; j < 3; j++) {
            rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(j), ts + j));
        }
    }

    client.putRow(new PutRowRequest(rowPutChange));
}

Mettre à jour une seule ligne

La méthode UpdateRow prend en charge les mises à jour inconditionnelles ainsi que les mises à jour conditionnelles basées sur l'existence de la ligne et les valeurs des colonnes.

Mise à jour sans conditions

Mettez à jour plusieurs colonnes, supprimez une version spécifique de données d'une colonne et retirez une colonne.

private static void updateRow(SyncClient client, String pkValue) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the table.
    RowUpdateChange rowUpdateChange = new RowUpdateChange("<TABLE_NAME>", primaryKey);

    // Update columns.
    for (int i = 0; i < 10; i++) {
        rowUpdateChange.put(new Column("Col" + i, ColumnValue.fromLong(i)));
    }

    // Delete a specific version of data from a column.
    rowUpdateChange.deleteColumn("Col10", 1465373223000L);

    // Remove a column.
    rowUpdateChange.deleteColumns("Col11");

    client.updateRow(new UpdateRowRequest(rowUpdateChange));
}

Conditions d'existence de la ligne et de valeur de colonne

Mettez à jour une ligne lorsque celle-ci existe et que la valeur de Col0 est supérieure à 100.

private static void updateRow(SyncClient client, String pkValue) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the table.
    RowUpdateChange rowUpdateChange = new RowUpdateChange("<TABLE_NAME>", primaryKey);

    // Specify a row existence condition and a column-based condition that expect the specified row to exist and the value of the Col0 column to be greater than 100.
    Condition condition = new Condition(RowExistenceExpectation.EXPECT_EXIST);
    condition.setColumnCondition(new SingleColumnValueCondition("Col0",
            SingleColumnValueCondition.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100)));
    rowUpdateChange.setCondition(condition);

    // Update columns.
    for (int i = 0; i < 10; i++) {
        rowUpdateChange.put(new Column("Col" + i, ColumnValue.fromLong(i)));
    }

    // Delete a specific version of data from a column.
    rowUpdateChange.deleteColumn("Col10", 1465373223000L);

    // Remove a column.
    rowUpdateChange.deleteColumns("Col11");

    client.updateRow(new UpdateRowRequest(rowUpdateChange));
}

Écrire plusieurs lignes simultanément

L'exemple suivant envoie une requête BatchWriteRow contenant deux opérations PutRow, une opération UpdateRow et une opération DeleteRow.

private static void batchWriteRow(SyncClient client) {
    BatchWriteRowRequest batchWriteRowRequest = new BatchWriteRowRequest();

    // Construct rowPutChange1.
    PrimaryKeyBuilder pk1Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    pk1Builder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("pk1"));
    // Specify the name of the data table.
    RowPutChange rowPutChange1 = new RowPutChange("<TABLE_NAME>", pk1Builder.build());
    // Add columns.
    for (int i = 0; i < 10; i++) {
        rowPutChange1.addColumn(new Column("Col" + i, ColumnValue.fromLong(i)));
    }
    // Add rowPutChange1 to the code of the batch operation.
    batchWriteRowRequest.addRowChange(rowPutChange1);

    // Construct rowPutChange2.
    PrimaryKeyBuilder pk2Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    pk2Builder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("pk2"));
    // Specify the name of the data table.
    RowPutChange rowPutChange2 = new RowPutChange("<TABLE_NAME>", pk2Builder.build());
    // Add columns.
    for (int i = 0; i < 10; i++) {
        rowPutChange2.addColumn(new Column("Col" + i, ColumnValue.fromLong(i)));
    }
    // Add rowPutChange2 to the code of the batch operation.
    batchWriteRowRequest.addRowChange(rowPutChange2);

    // Construct rowUpdateChange.
    PrimaryKeyBuilder pk3Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    pk3Builder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("pk3"));
    // Specify the name of the data table.
    RowUpdateChange rowUpdateChange = new RowUpdateChange("<TABLE_NAME>", pk3Builder.build());
    // Add columns.
    for (int i = 0; i < 10; i++) {
        rowUpdateChange.put(new Column("Col" + i, ColumnValue.fromLong(i)));
    }
    // Remove a column.
    rowUpdateChange.deleteColumns("Col10");
    // Add rowUpdateChange to the code of the batch operation.
    batchWriteRowRequest.addRowChange(rowUpdateChange);

    // Construct rowDeleteChange.
    PrimaryKeyBuilder pk4Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    pk4Builder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("pk4"));
    // Specify the name of the data table.
    RowDeleteChange rowDeleteChange = new RowDeleteChange("<TABLE_NAME>", pk4Builder.build());
    // Add rowDeleteChange to the code of the batch operation.
    batchWriteRowRequest.addRowChange(rowDeleteChange);

    BatchWriteRowResponse response = client.batchWriteRow(batchWriteRowRequest);

    System.out.println("Whether all operations are successful:" + response.isAllSucceed());
    if (!response.isAllSucceed()) {
        for (BatchWriteRowResponse.RowResult rowResult : response.getFailedRows()) {
            System.out.println("Failed rows:" + batchWriteRowRequest.getRowChange(rowResult.getTableName(), rowResult.getIndex()).getPrimaryKey());
            System.out.println("Cause of failures:" + rowResult.getError());
        }
        /**
         * You can use the createRequestForRetry method to construct another request to retry the operations on failed rows. Only the retry request is constructed here.
         * We recommend that you use the custom retry policy in Tablestore SDKs as the retry method. This feature allows you to retry failed rows after batch operations. After you set the retry policy, you do not need to add retry code to call the operation.
         */
        BatchWriteRowRequest retryRequest = batchWriteRowRequest.createRequestForRetry(response.getFailedRows());
    }
}

Facturation

Les opérations d'écriture sont facturées en fonction du nombre de CU consommés. Les CU de lecture et d'écriture mesurés ainsi que les CU de lecture et d'écriture réservés sont facturés séparément. Le type d'instance détermine quel type de CU est consommé.

Remarque

Pour plus d'informations sur les types d'instances et les CU, consultez les rubriques Instances et Débit de lecture et d'écriture.

Calcul des CU d'écriture

Opération Formule
PutRow Arrondi à l'entier supérieur : (Taille de toutes les colonnes de clé primaire + Taille des colonnes d'attributs insérées) / 4 Ko
UpdateRow Arrondi à l'entier supérieur : (Taille de toutes les colonnes de clé primaire + Taille des colonnes d'attributs mises à jour) / 4 Ko. Pour les opérations de suppression de colonne, la longueur du nom de la colonne compte comme taille de colonne.
DeleteRow (dans BatchWriteRow) Arrondi à l'entier supérieur : Taille de toutes les colonnes de clé primaire / 4 Ko

Calcul des CU de lecture

Les CU de lecture sont consommés uniquement lorsque le paramètre condition n'est pas défini sur IGNORE.

Opération Formule Condition non respectée
PutRow Arrondi à l'entier supérieur : Taille de toutes les colonnes de clé primaire / 4 Ko L'opération échoue. Consomme 1 CU d'écriture et 1 CU de lecture.
UpdateRow Arrondi à l'entier supérieur : Taille de toutes les colonnes de clé primaire / 4 Ko L'opération échoue. Consomme 1 CU d'écriture et 1 CU de lecture.
DeleteRow (dans BatchWriteRow) Arrondi à l'entier supérieur : Taille de toutes les colonnes de clé primaire / 4 Ko L'opération échoue. Consomme 1 CU d'écriture et 1 CU de lecture.