<commit_before># Marten.PLv8

TODO -- talk about installing the separate nuget

## The Patching API

::: tip INFO
Using the Patching API in Marten requires the usage of Postgresql's [PLV8 extension](https://github.com/plv8/plv8).
:::

Marten's Patching API is a mechanism to update persisted documents without having to first load the document into memory.
"Patching" can be much more efficient at runtime in some scenarios because you avoid the "deserialize from JSON, edit, serialize
back to JSON" workflow.

As of 1.2, Marten supports mechanisms to:

1. Set the value of a persisted field or property
1. Add a field or property with value
1. Duplicate a field or property to one or more destinations
1. Increment a numeric value by some increment (1 by default)
1. Append an element to a child array, list, or collection at the end
1. Insert an element into a child array, list, or collection at a given position
1. Remove an element from a child array, list, or collection
1. Rename a persisted field or property to a new name for structural document changes
1. Delete a persisted field or property

The patch operation can be configured to either execute against a single document by supplying its id, or with a _Where_ clause expression.
In all cases, the property or field being updated can be a deep accessor like `Target.Inner.Color`.

### Patching by Where Expression

To apply a patch to all documents matching a given criteria, use the following syntax:

<!-- snippet: sample_set_an_immediate_property_by_where_clause --><commit_msg>Add docs for Marten.PLv8<commit_after># Marten.PLv8

Marten provides **Marten.PLv8** plugin to use [PLV8](https://plv8.github.io/) based Patch and Transform operations on stored documents. Install it through the [NuGet package](Install-Package Marten.PLv8).

```powershell
Install-Package Marten.PLv8
```

Call `UseJavascriptTransformsAndPatching()` as part of `DocumentStore` setup to enable it. You can also optionally configure custom JavaScript transformations as part of this method.

A sample setup is shown below:
<!-- snippet: sample_loading_js_transform_files -->
<a id='snippet-sample_loading_js_transform_files'></a>
```cs
var store = DocumentStore.For(_ =>
{
    _.Connection(ConnectionSource.ConnectionString);

    _.UseJavascriptTransformsAndPatching(transforms =>
    {
        // Let Marten derive the transform name from the filename
        transforms.LoadFile("get_fullname.js");

        // Explicitly define the transform name yourself
        transforms.LoadFile("default_username.js", "set_default_username");
    });

});
```
<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten.PLv8.Testing/Transforms/document_transforms.cs#L36-L52' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_loading_js_transform_files' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

## The Patching API

::: tip INFO
Using the Patching API in Marten requires the usage of Postgresql's [PLV8 extension](https://github.com/plv8/plv8).
:::

Marten's Patching API is a mechanism to update persisted documents without having to first load the document into memory.
"Patching" can be much more efficient at runtime in some scenarios because you avoid the "deserialize from JSON, edit, serialize
back to JSON" workflow.

As of 1.2, Marten supports mechanisms to:

1. Set the value of a persisted field or property
1. Add a field or property with value
1. Duplicate a field or property to one or more destinations
1. Increment a numeric value by some increment (1 by default)
1. Append an element to a child array, list, or collection at the end
1. Insert an element into a child array, list, or collection at a given position
1. Remove an element from a child array, list, or collection
1. Rename a persisted field or property to a new name for structural document changes
1. Delete a persisted field or property

The patch operation can be configured to either execute against a single document by supplying its id, or with a _Where_ clause expression.
In all cases, the property or field being updated can be a deep accessor like `Target.Inner.Color`.

### Patching by Where Expression

To apply a patch to all documents matching a given criteria, use the following syntax:

<!-- snippet: sample_set_an_immediate_property_by_where_clause -->
{'fraction_non_alphanumeric': 0.07208659603869184, 'fraction_numerical': 0.009903270382312299, 'mean_word_length': 4.553708439897698, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 17, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2239846', 'n_tokens_mistral': 1203, 'n_tokens_neox': 1153, 'n_words': 568}