From 6592b365a746e60f4eee616ad350442938db6123 Mon Sep 17 00:00:00 2001 From: Florent Biville Date: Sun, 14 Jan 2024 20:39:25 +0100 Subject: [PATCH] Centralize batching documentation into single include file --- docs/includes/_batching.md | 15 +++++ docs/reference-features.md | 116 +++---------------------------------- 2 files changed, 24 insertions(+), 107 deletions(-) create mode 100644 docs/includes/_batching.md diff --git a/docs/includes/_batching.md b/docs/includes/_batching.md new file mode 100644 index 00000000..d8fb2c6c --- /dev/null +++ b/docs/includes/_batching.md @@ -0,0 +1,15 @@ +Since this operation can potentially affect a lot of data, running the change in a single transaction may be +infeasible since the transaction would likely run either too slow, or even out of memory. + +To prevent this, `enableBatchImport` must be set to `true`. +Since it relies on `CALL {} IN TRANSACTIONS` under the hood, the enclosing change set's `runInTransaction` must also be set to `false`. +This results in the change being executed in batches. + +!!! warning + This setting only works if the target Neo4j instance supports `CALL {} IN TRANSACTIONS` (version 4.4 and later). + If not, the Neo4j plugin will run the change in a single, autocommit transaction. + + Make sure to read about [the consequences of changing `runInTransaction`](#change-sets-runintransaction). + +The `batchSize` attribute controls how many transactions run. +If the attribute is not set, the batch size is defined on the Neo4j server side. diff --git a/docs/reference-features.md b/docs/reference-features.md index 28c96b3b..e1d72206 100644 --- a/docs/reference-features.md +++ b/docs/reference-features.md @@ -363,18 +363,7 @@ As illustrated below, the main attributes of the refactoring are: {! include '../src/test/resources/e2e/rename-label/changeLog-simple.yaml' !} ~~~~ -Since this operation can potentially affect a lot of nodes, running the change in a single transaction may be -infeasible since the transaction would likely run either too slow, or even run out of memory. - -To prevent this, `enableBatchImport` must be set to `true`. -Since it relies on `CALL {} IN TRANSACTIONS` under the hood, the enclosing change set's `runInTransaction` must also be set to `false`. -This results in the rename being executed in batches. - -!!! warning - This setting only works if the target Neo4j instance supports `CALL {} IN TRANSACTIONS` (version 4.4 and later). - If not, the Neo4j plugin will run the label rename in a single, autocommit transaction. - - Make sure to read about [the consequences of changing `runInTransaction`](#change-sets-runintransaction). +{! include-markdown 'includes/_batching.md' !} === "XML" ~~~~xml @@ -393,9 +382,6 @@ This results in the rename being executed in batches. {! include '../src/test/resources/e2e/rename-label/changeLog-simple-batched.yaml' !} ~~~~ -As shown above, the `batchSize` attribute can be set in order to control how many transactions are going to be executed. -If the attribute is not set, the batch size will depend on the Neo4j server's default value. - #### Partial Rename The following attributes can also be set, in order to match only a subset of the nodes with the label specified in `from`: @@ -429,15 +415,7 @@ The following attributes can also be set, in order to match only a subset of the Since this operation can potentially affect a lot of nodes, running the change in a single transaction may be infeasible since the transaction would likely run either too slow, or even run out of memory. -To prevent this, `enableBatchImport` must be set to `true`. -Since it relies on `CALL {} IN TRANSACTIONS` under the hood, the enclosing change set's `runInTransaction` must also be set to `false`. -This results in the rename being executed in batches. - -!!! warning - This setting only works if the target Neo4j instance supports `CALL {} IN TRANSACTIONS` (version 4.4 and later). - If not, the Neo4j plugin will run the label rename in a single, autocommit transaction. - - Make sure to read about [the consequences of changing `runInTransaction`](#change-sets-runintransaction). +{! include-markdown 'includes/_batching.md' !} === "XML" @@ -457,9 +435,6 @@ This results in the rename being executed in batches. {! include '../src/test/resources/e2e/rename-label/changeLog-pattern-batched.yaml' !} ~~~~ -As shown above, the `batchSize` attribute can be set in order to control how many transactions are going to be executed. -If the attribute is not set, the batch size will depend on the Neo4j server's default value. - ### Relationship Type Rename |Required plugin version|4.25.0.1| @@ -492,18 +467,7 @@ As illustrated below, the main attributes of the refactoring are: {! include '../src/test/resources/e2e/rename-type/changeLog-simple.yaml' !} ~~~~ -Since this operation can potentially affect a lot of relationships, running the change in a single transaction may be -infeasible since the transaction would likely run either too slow, or even run out of memory. - -To prevent this, `enableBatchImport` must be set to `true`. -Since it relies on `CALL {} IN TRANSACTIONS` under the hood, the enclosing change set's `runInTransaction` must also be set to `false`. -This results in the rename being executed in batches. - -!!! warning - This setting only works if the target Neo4j instance supports `CALL {} IN TRANSACTIONS` (version 4.4 and later). - If not, the Neo4j plugin will run the type rename in a single, autocommit transaction. - - Make sure to read about [the consequences of changing `runInTransaction`](#change-sets-runintransaction). +{! include-markdown 'includes/_batching.md' !} === "XML" ~~~~xml @@ -522,9 +486,6 @@ This results in the rename being executed in batches. {! include '../src/test/resources/e2e/rename-type/changeLog-simple-batched.yaml' !} ~~~~ -As shown above, the `batchSize` attribute can be set in order to control how many transactions are going to be executed. -If the attribute is not set, the batch size will depend on the Neo4j server's default value. - #### Partial Rename The following attributes can also be set, in order to match only a subset of the relationships with the type specified in `from`: @@ -555,19 +516,7 @@ The following attributes can also be set, in order to match only a subset of the {! include '../src/test/resources/e2e/rename-type/changeLog-pattern.yaml' !} ~~~~ -Since this operation can potentially affect a lot of relationships, running the change in a single transaction may be -infeasible since the transaction would likely run either too slow, or even run out of memory. - -To prevent this, `enableBatchImport` must be set to `true`. -Since it relies on `CALL {} IN TRANSACTIONS` under the hood, the enclosing change set's `runInTransaction` must also be set to `false`. -This results in the rename being executed in batches. - -!!! warning - This setting only works if the target Neo4j instance supports `CALL {} IN TRANSACTIONS` (version 4.4 and later). - If not, the Neo4j plugin will run the type rename in a single, autocommit transaction. - - Make sure to read about [the consequences of changing `runInTransaction`](#change-sets-runintransaction). - +{! include-markdown 'includes/_batching.md' !} === "XML" ~~~~xml @@ -586,10 +535,6 @@ This results in the rename being executed in batches. {! include '../src/test/resources/e2e/rename-type/changeLog-pattern-batched.yaml' !} ~~~~ -As shown above, the `batchSize` attribute can be set in order to control how many transactions are going to be executed. -If the attribute is not set, the batch size will depend on the Neo4j server's default value. - - ### Relationship Direction Inversion |Required plugin version|4.25.1.1| @@ -621,18 +566,7 @@ As illustrated below, the main attributes of the refactoring are: {! include '../src/test/resources/e2e/invert-direction/changeLog-simple.yaml' !} ~~~~ -Since this operation can potentially affect a lot of relationships, running the change in a single transaction may be -infeasible since the transaction would likely run either too slow, or even run out of memory. - -To prevent this, `enableBatchImport` must be set to `true`. -Since it relies on `CALL {} IN TRANSACTIONS` under the hood, the enclosing change set's `runInTransaction` must also be set to `false`. -This results in the rename being executed in batches. - -!!! warning - This setting only works if the target Neo4j instance supports `CALL {} IN TRANSACTIONS` (version 4.4 and later). - If not, the Neo4j plugin will run the direction inversion in a single, autocommit transaction. - - Make sure to read about [the consequences of changing `runInTransaction`](#change-sets-runintransaction). +{! include-markdown 'includes/_batching.md' !} === "XML" ~~~~xml @@ -651,9 +585,6 @@ This results in the rename being executed in batches. {! include '../src/test/resources/e2e/invert-direction/changeLog-simple-batched.yaml' !} ~~~~ -As shown above, the `batchSize` attribute can be set in order to control how many transactions are going to be executed. -If the attribute is not set, the batch size will depend on the Neo4j server's default value. - #### Partial Inversion The following attributes can also be set, in order to match only a subset of the relationships with the type specified in `type`: @@ -684,19 +615,7 @@ The following attributes can also be set, in order to match only a subset of the {! include '../src/test/resources/e2e/invert-direction/changeLog-pattern.yaml' !} ~~~~ -Since this operation can potentially affect a lot of relationships, running the change in a single transaction may be -infeasible since the transaction would likely run either too slow, or even run out of memory. - -To prevent this, `enableBatchImport` must be set to `true`. -Since it relies on `CALL {} IN TRANSACTIONS` under the hood, the enclosing change set's `runInTransaction` must also be set to `false`. -This results in the rename being executed in batches. - -!!! warning - This setting only works if the target Neo4j instance supports `CALL {} IN TRANSACTIONS` (version 4.4 and later). - If not, the Neo4j plugin will run the direction inversion in a single, autocommit transaction. - - Make sure to read about [the consequences of changing `runInTransaction`](#change-sets-runintransaction). - +{! include-markdown 'includes/_batching.md' !} === "XML" ~~~~xml @@ -715,9 +634,6 @@ This results in the rename being executed in batches. {! include '../src/test/resources/e2e/invert-direction/changeLog-pattern-batched.yaml' !} ~~~~ -As shown above, the `batchSize` attribute can be set in order to control how many transactions are going to be executed. -If the attribute is not set, the batch size will depend on the Neo4j server's default value. - ### Property Rename |Required plugin version|4.25.1.1| @@ -751,18 +667,7 @@ As illustrated below, the main attributes of the refactoring are: {! include '../src/test/resources/e2e/rename-property/changeLog-all.yaml' !} ~~~~ -Since this operation can potentially affect a lot of entities, running the change in a single transaction (per entity type) may be -infeasible since the transaction would likely run either too slow, or even run out of memory. - -To prevent this, `enableBatchImport` must be set to `true`. -Since it relies on `CALL {} IN TRANSACTIONS` under the hood, the enclosing change set's `runInTransaction` must also be set to `false`. -This results in the rename being executed in batches. - -!!! warning - This setting only works if the target Neo4j instance supports `CALL {} IN TRANSACTIONS` (version 4.4 and later). - If not, the Neo4j plugin will run the property rename in a single, autocommit transaction per entity type (`ALL` will yield 2 transactions: 1 for nodes, 1 for relationships). - - Make sure to read about [the consequences of changing `runInTransaction`](#change-sets-runintransaction). +{! include-markdown 'includes/_batching.md' !} === "XML" @@ -782,9 +687,6 @@ This results in the rename being executed in batches. {! include '../src/test/resources/e2e/rename-property/changeLog-all-batched.yaml' !} ~~~~ -As shown above, the `batchSize` attribute can be set in order to control how many transactions are going to be executed. -If the attribute is not set, the batch size will depend on the Neo4j server's default value. - #### Node-only Property Rename When setting the `entityType` attribute to `NODE`, only the matching properties of nodes will be renamed: @@ -807,7 +709,7 @@ When setting the `entityType` attribute to `NODE`, only the matching properties {! include '../src/test/resources/e2e/rename-property/changeLog-node.yaml' !} ~~~~ -As for the global rename, batching is supported in case the change affects many nodes at once. +{! include-markdown 'includes/_batching.md' !} === "XML" @@ -849,7 +751,7 @@ When setting the `entityType` attribute to `RELATIONSHIP`, only the matching pro {! include '../src/test/resources/e2e/rename-property/changeLog-rel.yaml' !} ~~~~ -As for the global rename, batching is supported in case the change affects many relationships at once. +{! include-markdown 'includes/_batching.md' !} === "XML"