Elasticsearch:Copy data: Copy Slice

L'opération Copy réécrit les documents un par un. Par conséquent, la durée de l'opération ainsi que la surcharge en lecture et en écriture augmentent avec le volume de données.

Sémantique de la copie de données

L'opération Copy produit une copie indépendante des données et laisse le Slice source à son emplacement d'origine. La liste suivante décrit l'allocation du Slice de destination et le traitement des documents pendant la copie.

• Le Slice source et le Slice de destination doivent appartenir à la même Collection et ne doivent pas porter le même nom.

• Au démarrage de l'opération Copy, le Slice de destination ne doit contenir aucun document indexable. Sinon, l'opération renvoie l'erreur target_not_empty. Cette vérification ne verrouille pas le Slice de destination ; des écritures concurrentes peuvent donc toujours provoquer des conflits entre des documents partageant le même ID.

• Si le Slice de destination n'existe pas, l'opération Copy l'enregistre automatiquement selon la règle d'allocation actuelle de la Collection pour les Slices réguliers, même si auto_create_slice=false. Si le Slice de destination existe déjà, l'opération utilise son Backing et l'emplacement de ses shards. Les échecs d'admission ultérieurs ne suppriment pas automatiquement le Slice de destination nouvellement enregistré.

• L'opération Copy peut copier des données entre différents Backings et shards. Le Slice source et le Slice de destination peuvent utiliser des configurations différentes en termes de nombre de shards et de partitions de routage ; les documents sont réindexés selon la configuration de destination.

• L'API Copy ne propose aucun paramètre pour spécifier le Backing ou le shard de destination, et elle ne garantit pas qu'un nouveau Slice de destination et le Slice source se trouvent sur des shards différents. Si vous ajustez le nombre de shards ou la configuration des partitions de routage pour les Backings futurs, seuls les Backings créés par la suite utiliseront la nouvelle configuration. L'opération Copy ne modifie pas la disposition des shards d'un Slice de destination existant. Pour plus d'informations, consultez Paramètres prenant effet sur les Backings suivants.

• L'opération Copy utilise des écritures de type « création uniquement » et n'écrase pas un document existant ayant le même _id dans le Slice de destination. Les conflits sont comptabilisés dans le champ version_conflicts, et la copie des documents restants se poursuit. Une fois l'opération terminée, vérifiez ce champ et traitez les documents partageant le même ID selon vos besoins métier.

• L'opération Copy préserve le contenu des documents, y compris le champ référencé par routing_field. Par exemple, lorsque routing_field=cluster_id et que cluster-a est copié vers cluster-b, le cluster_id du document de destination reste cluster-a. Pour réécrire ultérieurement les documents dans le Slice de destination via les opérations Index ou Bulk, spécifiez explicitement _slice=cluster-b et modifiez le cluster_id du document en cluster-b. Si vous réécrivez le document sans modification et omettez _slice ou routing, la valeur du champ acheminera le document vers le Slice source. Si vous spécifiez explicitement le Slice de destination mais conservez la valeur du champ source, la validation par défaut renvoie une erreur HTTP 400. Ne désactivez pas la validation pour contourner ce comportement. Ajustez la logique d'écriture avant que l'application ne bascule le trafic.

• En mode cluster vectoriel, l'opération Copy ne copie que les documents, et non le vecteur central du Slice. Un Slice de destination enregistré automatiquement ne possède pas de vecteur central et ne participe donc pas à la sélection automatique des Slices. Pour permettre au Slice de destination de participer, enregistrez un vecteur central séparément, ou enregistrez un Slice de destination vide avec un vecteur central avant d'exécuter l'opération Copy.

• Le Slice source et le Slice de destination restent lisibles et accessibles en écriture pendant l'opération Copy. Le résultat n'est donc pas un instantané atomique à un instant donné du Slice source.

• Le Slice source doit conserver l'intégralité du _source nécessaire à la reconstruction des documents. L'opération Copy est rejetée si _source est désactivé ou si un _source synthétique est utilisé. Elle est également rejetée lorsqu'un _source.includes non vide est configuré, ou lorsque _source.excludes exclut du contenu encore utilisé pour l'indexation, le tri, copy_to ou les multi-champs. L'exclusion de champs pouvant être récupérés en toute sécurité depuis l'index peut fonctionner. Le résultat de la validation côté serveur fait foi.

• L'opération Copy n'est actuellement pas prise en charge lorsque le Mapping du Slice source contient des champs d'inférence tels que semantic_text.

• Le pipeline d'ingestion par défaut ou final n'est pas exécuté à nouveau pendant l'opération Copy.

• Les documents sont réappliqués selon le Mapping actuel du Slice de destination. Par exemple, un nouveau multi-champ ajouté sera généré dans le Slice de destination. Évitez les modifications de Mapping susceptibles d'affecter l'interprétation des résultats pendant l'exécution de l'opération Copy.

Ajuster la configuration des shards de destination (facultatif)

Si vous n'avez pas besoin d'ajuster la configuration des shards, lancez directement l'opération Copy. L'API Copy ne permettant pas de spécifier un Backing de destination, suivez les étapes ci-dessous avant de démarrer la copie afin que le Slice de destination utilise un nombre différent de shards primaires ou de partitions de routage :

1. Définissez les paramètres pour les Backings suivants en utilisant Mettre à jour une Collection, puis pré-créez un Backing. Après avoir pré-créé plusieurs Backings, le système bascule la règle d'allocation pour les nouveaux Slices vers random.

2. Si la destination doit utiliser le Backing que vous venez de créer, ramenez la règle d'allocation à last.

3. Enregistrez le Slice de destination.

4. Vérifiez que le backing_index du Slice de destination utilise le nouveau Backing, puis démarrez l'opération Copy.

Copy : démarrer l'opération

Avant de démarrer l'opération Copy, assurez-vous que les données sources sont consultables et que la destination est un nouveau Slice ou un Slice ne contenant aucun document indexable. Les documents sources doivent satisfaire aux exigences relatives à _source et au Mapping décrites dans la section Sémantique de la copie de données. L'opération Copy lit les données sources et les écrit dans le Slice de destination, mais les écritures en cours ne sont pas synchronisées automatiquement. Gérez les données incrémentielles séparément avant de basculer le trafic.

Envoyez la requête suivante. Remplacez {collection}, {source} et {target} par le nom de la Collection, le nom du Slice source et le nom du Slice de destination :

POST /_slice_collection/{collection}/slices/{source}/_copy/{target}

Paramètres de requête :

Tous les paramètres du corps de la requête sont facultatifs :

L'exemple suivant démarre avec un worker, 500 documents par lot et un taux total de 500 documents par seconde. Ces valeurs sont fournies à titre d'exemple pour vous aider à contrôler la charge initiale ; elles ne constituent ni des valeurs par défaut ni des garanties de débit. Évaluez la taille des documents, la surcharge des requêtes sources et la charge d'écriture de destination avant de les ajuster.

POST /_slice_collection/knowledge-chunks/slices/tenant-a/_copy/tenant-a-copy?wait_for_completion=false
{
  "workers": 1,
  "batch_size": 500,
  "requests_per_second": 500
}

Une requête asynchrone renvoie le code HTTP 202 Accepted. Enregistrez l'identifiant copy_id issu de la réponse, et utilisez les URL status_url et cancel_url retournées par le serveur. L'en-tête de réponse Location fournit également l'URL de requête d'état. Exemple de réponse :

{
  "copy_id": "opaque-copy-id",
  "completed": false,
  "timed_out": false,
  "state": "RUNNING",
  "source": "tenant-a",
  "target": "tenant-a-copy",
  "progress": { "total": 0, "created": 0, "version_conflicts": 0 },
  "status_url": "/_slice_collection/knowledge-chunks/_copy/opaque-copy-id",
  "cancel_url": "/_slice_collection/knowledge-chunks/_copy/opaque-copy-id/_cancel"
}

La réponse inclut le champ workers uniquement après détermination de la concurrence d'exécution, et sa valeur est toujours supérieure à 0. Ne supposez pas que la réponse retournée immédiatement après la soumission contient ce champ. En cas d'échec de l'opération Copy, la réponse inclut également le champ error, qui décrit la cause de l'échec.

L'identifiant copy_id est un identifiant opaque qui peut contenir des caractères réservés aux URL, tels que les deux-points. Encodez l'identifiant en URL si vous construisez vous-même l'URL de requête d'état. Utilisez les champs status_url et cancel_url retournés dans la réponse.

Une réponse pour une opération Copy en cours contient l'objet progress. Seul l'état state=SUCCEEDED utilise le champ result. Les états FAILED et CANCELLED utilisent également le champ progress pour signaler le travail accompli avant la fin de l'opération Copy. Ces trois états terminaux contiennent completed=true et took, qui indique le temps écoulé en millisecondes. Le champ version_conflicts apparaît dans l'objet progress ou result correspondant.

Avec la valeur par défaut wait_for_completion=true, l'API renvoie le code HTTP 200 si l'opération Copy atteint un état terminal dans le délai spécifié par timeout. Si l'attente expire, l'API renvoie le code HTTP 202 avec timed_out=true, et l'opération Copy continue de s'exécuter en arrière-plan. La déconnexion du client n'annule pas automatiquement l'opération Copy.

Copy : interroger l'état

Envoyez la requête suivante. Remplacez <copy_id> par l'identifiant copy_id retourné par la requête de démarrage :

GET /_slice_collection/knowledge-chunks/_copy/<copy_id>

Une requête d'état réussie renvoie toujours le code HTTP 200, y compris lorsque state=FAILED. Vérifiez toujours les champs state et error au lieu de vous fier uniquement au code d'état HTTP.

Interrogez l'état de l'opération Copy à intervalles réguliers et arrêtez le sondage une fois que l'opération a atteint un état terminal. L'état SUCCEEDED signifie que l'opération Copy est terminée, mais pas que toutes les données de destination sont consultables. Avant de vérifier les résultats ou de basculer le trafic, attendez l'actualisation en arrière-plan, puis vérifiez les résultats de requête du Slice de destination. Si la latence des requêtes à froid est critique pour votre charge de travail, préchauffez le Slice de destination à l'avance. Si l'opération Copy reste longtemps dans l'état RUNNING et progresse lentement, il est possible que le serveur ait réduit automatiquement la taille du lot en raison de la pression mémoire. Il s'agit d'un comportement d'autoprotection ; continuez donc à interroger l'état à intervalles réguliers au lieu d'annuler et de relancer immédiatement l'opération Copy.

PUT /_cluster/settings
{
  "persistent": {
    "apack.slice_collection.copy.reservation_retention": "1d"
  }
}

Copy : annuler l'opération

Envoyez la requête suivante. Remplacez <copy_id> par l'identifiant copy_id retourné par la requête de démarrage :

POST /_slice_collection/knowledge-chunks/_copy/<copy_id>/_cancel

L'annulation de l'opération Copy ne supprime ni le Slice de destination ni les documents déjà copiés. Lorsqu'une annulation asynchrone est acceptée, l'API renvoie le code HTTP 202 avec state=CANCELLING. Continuez à interroger l'état jusqu'à ce que completed=true, ce qui renvoie généralement state=CANCELLED. Si l'opération Copy a réussi ou échoué avant que l'annulation ne prenne effet, l'état terminal correspondant est renvoyé. Une fois l'opération Copy terminée, la réponse n'inclut plus le champ cancel_url. L'annulation d'une opération Copy déjà terminée renvoie l'état actuel et le code HTTP 200.

Codes d'erreur

Le tableau suivant répertorie les erreurs renvoyées par l'API Copy au démarrage :

Étapes suivantes

Une fois l'opération Copy terminée, vérifiez l'état et le résultat de la copie au niveau de l'application, puis basculez le trafic de service vers le Slice de destination via votre configuration métier.

Pour obtenir des informations sur le choix entre Copy et Branch, consultez Branche de données inscriptibles : Branch Slice (Bêta).