Elasticsearch:Branch Slice (Beta)

Prérequis

• La source et la cible appartiennent à la même Collection et partagent le Mapping et les paramètres d'index. Les écritures indépendantes n'affectent que le contenu des documents.

• La cible et la source résident sur le même shard du même Backing. La valeur index.routing_partition_size du Backing contenant la source doit être 1, ce qui correspond à la valeur par défaut. Si la valeur est supérieure à 1, la création de Branch n'est pas prise en charge. Envisagez d'utiliser Copy Slice.

• La cible doit utiliser un nouveau nom et ne peut pas reprendre un Slice existant. Pour plus d'informations sur les demandes dupliquées et les conflits de noms, consultez les sections Créer une branche et Erreurs courantes.

• Le compte nécessite l'autorisation manage sur la Collection. Pour savoir comment configurer cette autorisation, consultez Autorisations de Collection.

Avant d'intégrer Branch Slice, assurez-vous que votre activité peut accepter les limitations suivantes :

• Échec global des requêtes — Tant que la cible est une Active Branch (une cible de branche qui n'a pas encore été convertie en Slice standard), une requête multi-Slice ou une requête _slice=_all incluant la cible renvoie un code HTTP 409 au lieu de résultats partiels. Une requête synchrone _warm_slice renvoie également un code HTTP 409, et la fonction Explain n'est pas prise en charge.

• Résultats incomplets — Une requête CAT qui renvoie plusieurs lignes, ou qui trie par s=docs.count, ne comptabilise que les données écrites dans la cible elle-même.

• État de la source — Si le Slice source est toujours une Active Branch, seule l'option wait_for_commit=false est prise en charge. Spécifier wait_for_commit=true renvoie un code HTTP 400.

• Profondeur d'héritage — Un maximum de 8 niveaux d'héritage est pris en charge.

• Quotas — Des limites s'appliquent au nombre de Branches en cours de préparation sur le même shard, au nombre d'Active Branches et à la taille des métadonnées de Branch. Lorsqu'une limite est atteinte, seules les nouvelles créations de Branch sont rejetées. Les lectures et écritures sur les Branches existantes et leurs données continuent d'être traitées.

• Indisponibilité avec nouvelle tentative possible — Pendant la transition de l'état de la Branch, ou lorsque les données validées requises pour une lecture sont temporairement indisponibles, les opérations de lecture et dérivées renvoient un code HTTP 503 permettant une nouvelle tentative.

Pour plus de détails, consultez les sections Différences de comportement pendant la phase Active et Erreurs courantes. Pour comparer Branch Slice avec Copy Slice, reportez-vous aux Informations connexes.

Créer une nouvelle Branch

Envoyez la requête suivante pour créer une Branch :

PUT /_slice_collection/{collection}/slices/{source}/_branch/{target}

Le paramètre de requête suivant est pris en charge :

Le corps de la requête peut être omis ou défini sur {}. Actuellement, le champ facultatif suivant est le seul disponible :

L'exemple suivant crée la Branch tenant-a-preview à partir du Slice source tenant-a :

PUT /_slice_collection/knowledge-chunks/slices/tenant-a/_branch/tenant-a-preview
{}

La première création réussie renvoie un code HTTP 201 :

{
  "target_slice": "tenant-a-preview",
  "target_uid": "opaque-target-uid",
  "wait_for_commit": false
}

target_uid représente l'identité interne de la cible et sert à confirmer si le résultat appartient à la même création. N'analysez pas son contenu et ne l'utilisez pas comme _slice. Pour accéder à la cible, continuez à spécifier le nom métier tenant-a-preview, qui correspond à target_slice dans la réponse.

L'envoi répété de la même requête pour la même relation Active Branch est idempotent et renvoie un code HTTP 200 ainsi que le même target_uid. L'API ne reprend pas une cible existante. Si le nom de la cible est déjà utilisé ou si un autre conflit empêche la création, un code HTTP 409 est renvoyé. Pour la liste complète des scénarios HTTP 409, consultez la section Erreurs courantes.

Un délai d'expiration de la requête n'annule pas la progression de la création déjà persistée. Ne concluez pas à partir d'un délai d'expiration que la création a été annulée. Interrogez le Slice cible pour confirmer sa disponibilité, puis gérez la nouvelle tentative comme décrit dans la section Erreurs courantes.

Une fois la réponse de création reçue, vérifiez que la cible est lisible et qu'elle renvoie les données attendues. Pour les méthodes de vérification, consultez la section Vérification des requêtes et du nombre de documents.

PUT /_slice_collection/knowledge-chunks/slices/tenant-a/_branch/tenant-a-durable-preview
{
  "wait_for_commit": true
}

Sémantique de lecture et d'écriture

Une fois la réponse de création reçue, la cible peut être immédiatement utilisée pour les opérations GET, MGet et Search sur un Slice unique. Les requêtes de document sélectionnent toujours la cible en spécifiant _slice=tenant-a-preview. Les paramètres et autorisations sont identiques à ceux d'un Slice standard. La requête suivante recherche dans le Slice cible :

GET /knowledge-chunks/_search?_slice=tenant-a-preview

Les règles de lecture et d'écriture suivantes s'appliquent à une cible de Branch :

• Pendant l'utilisation normale, la cible lit la version des données source fixée au moment de la création. Les documents écrits dans la source par la suite n'apparaissent pas automatiquement dans la cible. Pour l'exception de récupération d'erreur précoce qui s'applique à la valeur par défaut wait_for_commit=false, consultez la section Créer une branche, qui décrit les valeurs de wait_for_commit.

• Les opérations Index, Update et Delete sur la cible n'affectent que la cible et ne modifient pas la source.

• Une Branch ne modifie pas les champs métier dans les documents hérités vers le nom de la cible. Si routing_field est configuré, les écritures ultérieures sur la cible doivent sélectionner le Slice cible, et le champ de routage dans le document écrit doit correspondre à la cible. Sinon, le document peut être réécrit dans la source en fonction de la valeur du champ source, ou l'écriture peut être rejetée car la portée explicitement spécifiée ne correspond pas au champ.

• Lorsque vous écrivez un document avec le même _id qu'un document hérité dans la cible, le nouveau document remplace l'ancien document dans la vue héritée.

• Lorsque vous supprimez un document hérité de la cible, le document devient invisible uniquement dans la cible. Le document dans la source reste inchangé.

• Pour supprimer la cible, utilisez l'API standard Supprimer un Slice. Une fois la relation de Branch libérée, une cible portant le même nom peut être enregistrée à nouveau en tant que Slice standard. Le nouveau Slice ne peut pas voir les données héritées par l'ancienne Branch.

Une cible de Branch peut également servir de source pour une nouvelle Branch. Dans ce cas, seule l'option wait_for_commit=false est prise en charge, et la spécification de true renvoie un code HTTP 400. Un maximum de 8 niveaux d'héritage est pris en charge.

Lorsque vous créez une Branch à partir d'une cible de Branch, les règles suivantes s'appliquent :

• Le système capture la vue validée complète la plus récente de la cible sans attendre les écritures en cours.

• L'inclusion d'une écriture dans la nouvelle Branch dépend du fait que cette écriture soit déjà incluse dans la version validée effectivement capturée.

• L'heure d'envoi de la requête par le client ne peut pas servir de limite pour les écritures métier.

Différences de comportement pendant la phase Active

Avant que la cible ne soit convertie en Slice standard, elle est appelée Active Branch. Les différences suivantes s'appliquent pendant cette phase. Certaines d'entre elles provoquent l'échec de la requête entière au lieu de renvoyer des résultats partiels. Avant d'intégrer cette fonctionnalité, assurez-vous que votre activité peut les accepter :

Si votre activité comporte des statistiques ou des requêtes de récupération couvrant tous les Slices, évaluez avant de créer une Branch si ces requêtes risquent d'échouer parce qu'elles incluent une Active Branch. Si vous devez exécuter immédiatement une requête multi-Slices, interrogez cette cible séparément ou effectuez une nouvelle tentative après sa conversion en Slice standard.

Conversion automatique en Slice standard

Une cible de Branch est automatiquement convertie en Slice standard en arrière-plan. La conversion analyse une fois l'historique visible complet et écrit les données héritées en tant que données de la cible elle-même. L'ensemble du processus ne bloque pas les lectures ou écritures métier. Une fois la conversion terminée, toutes les différences de comportement décrites pour la phase Active disparaissent.

La conversion est planifiée en arrière-plan. Les conditions de déclenchement incluent l'écoulement d'un certain temps après la création, l'atteinte d'un certain seuil pour le nombre de documents hérités remplacés ou supprimés, et l'atteinte d'une certaine taille pour les métadonnées de la Branch. Il s'agit de conditions de planification, et non de délais d'achèvement, de limites de nombre de mises à jour ou de limites de rejet d'écriture. Les seuils spécifiques sont des valeurs internes susceptibles de changer pendant la phase Beta. Le respect d'une condition ne signifie pas que la conversion se termine immédiatement, et le non-respect d'une condition n'affecte pas les lectures ou écritures normales sur la cible.

Un arriéré de tâches en arrière-plan ou un budget mémoire insuffisant pour une exécution unique ne provoque pas l'échec des opérations GET, Search, Index, Update ou Delete sur une cible existante. Le système annule et relance la tâche en arrière-plan. Les résultats de conversion déjà réussis et les écritures métier ultérieures restent valides.

Pour vérifier si la cible a été convertie en Slice standard, observez si les limitations d'Active Branch disparaissent dans les requêtes métier réelles. Ne sondez pas la progression de la conversion avec des requêtes _slice=_all fréquentes ou en soumettant répétitivement des tâches de warming. Les lectures et écritures sur un Slice unique n'ont pas besoin d'attendre la conversion.

Vérification des requêtes et du nombre de documents

Après avoir créé une Branch, vérifiez que la cible est lisible et qu'elle renvoie les données attendues. Pour interroger la source et la cible séparément dans une seule requête, utilisez Multi Search et sélectionnez un seul Slice dans chaque sous-requête :

POST /knowledge-chunks/_msearch
{ "_slice": "tenant-a" }
{ "query": { "match_all": {} } }
{ "_slice": "tenant-a-preview" }
{ "query": { "match_all": {} } }

Le corps de la requête utilise le format NDJSON et doit se terminer par un saut de ligne. Chaque sous-requête renvoie un résultat ou une erreur séparément, et l'application doit vérifier chaque élément. Cette méthode ne génère pas automatiquement de résultats de tri ou d'agrégation unifiés entre les Slices.

Pour vérifier le nombre total de documents consultables dans la cible, interrogez directement le Slice cible. include_doc_count=true effectue une requête de données supplémentaire et convient pour une vérification peu fréquente. Omettez ce paramètre si vous devez uniquement vérifier l'existence du Slice :

GET /_slice_collection/knowledge-chunks/slices/tenant-a-preview?include_doc_count=true

Lorsque l'état de la Branch est en transition, ou lorsque les données validées requises pour la lecture sont temporairement indisponibles, le nœud actuel peut être temporairement incapable de fournir toutes les données de la Branch. Les opérations de lecture ou dérivées renvoient un code HTTP 503 permettant une nouvelle tentative. Pour le contrat de nouvelle tentative, consultez la section Erreurs courantes.

Erreurs courantes

Pour les limites spécifiques de nombre et de taille, consultez Limites de Branch Slice (Beta).

Informations connexes

Pour savoir comment choisir entre Branch Slice et Copy Slice, consultez Comparer Branch Slice et Copy Slice.