Skip to content

Commit

Permalink
Centralize batching documentation into single include file
Browse files Browse the repository at this point in the history
  • Loading branch information
@fbiville
fbiville committed Jan 17, 2024
1 parent e0eee3f commit 6592b36
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 107 deletions.
15 changes: 15 additions & 0 deletions docs/includes/_batching.md
View file
Original file line number Diff line number Diff line change
@@ -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.
116 changes: 9 additions & 107 deletions docs/reference-features.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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`:
Expand Down Expand Up @@ -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"
Expand All @@ -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|
Expand Down Expand Up @@ -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
Expand All @@ -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`:
Expand Down Expand Up @@ -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
Expand All @@ -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|
Expand Down Expand Up @@ -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
Expand All @@ -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`:
Expand Down Expand Up @@ -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
Expand All @@ -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|
Expand Down Expand Up @@ -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"

Expand All @@ -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:
Expand All @@ -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"

Expand Down Expand Up @@ -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"

Expand Down

0 comments on commit 6592b36

Please sign in to comment.