Edit documents by function

Use a RHAI function to edit one or more documents directly in Meilisearch. The function receives each document and returns the modified document.

This feature is experimental and must be enabled through the experimental route.

POST /indexes/{index_uid}/documents/edit

cURL

cURL

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/documents/edit' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "function": "doc.new_field = `a]new[value`",
    "filter": "id > 3000",
    "context": {
      "max_title_length": 10
    }
  }'

import requests

url = "http://localhost:7700/indexes/{index_uid}/documents/edit"

payload = {
    "function": "<string>",
    "filter": "<unknown>",
    "context": "<unknown>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({function: '<string>', filter: '<unknown>', context: '<unknown>'})
};

fetch('http://localhost:7700/indexes/{index_uid}/documents/edit', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "7700",
  CURLOPT_URL => "http://localhost:7700/indexes/{index_uid}/documents/edit",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'function' => '<string>',
    'filter' => '<unknown>',
    'context' => '<unknown>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:7700/indexes/{index_uid}/documents/edit"

	payload := strings.NewReader("{\n  \"function\": \"<string>\",\n  \"filter\": \"<unknown>\",\n  \"context\": \"<unknown>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:7700/indexes/{index_uid}/documents/edit")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"function\": \"<string>\",\n  \"filter\": \"<unknown>\",\n  \"context\": \"<unknown>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:7700/indexes/{index_uid}/documents/edit")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"function\": \"<string>\",\n  \"filter\": \"<unknown>\",\n  \"context\": \"<unknown>\"\n}"

response = http.request(request)
puts response.read_body

202

{
  "taskUid": 147,
  "indexUid": null,
  "status": "enqueued",
  "type": "documentDeletion",
  "enqueuedAt": "2024-08-08T17:05:55.791772Z"
}

{
  "message": "The Authorization header is missing. It must use the bearer authorization method.",
  "code": "missing_authorization_header",
  "type": "auth",
  "link": "https://docs.meilisearch.com/errors#missing_authorization_header"
}

{
  "message": "Index `movies` not found.",
  "code": "index_not_found",
  "type": "invalid_request",
  "link": "https://docs.meilisearch.com/errors#index_not_found"
}

Authorizations

Authorization · string · header · required

An API key is a token that you provide when making API calls. Read more about how to secure your project.

Include the API key to the Authorization header, for instance:

-H 'Authorization: Bearer 6436fc5237b0d6e0d64253fbaac21d135012ecf1'

If you use a SDK, ensure you instantiate the client with the API key, for instance with JS SDK:

const client = new MeiliSearch({
  host: 'MEILISEARCH_URL',
  apiKey: '6436fc5237b0d6e0d64253fbaac21d135012ecf1'
});

Path Parameters

index_uid · string · required

Unique identifier of the index.

Query Parameters

customMetadata · string

A string that can be used to identify and filter tasks. This metadata is stored with the task and returned in task responses. Useful for tracking tasks from external systems or associating tasks with specific operations in your application.

Body

application/json

Request body for editing documents using a RHAI function

function · string · required

A RHAI function string to apply to each document. The function has access to a doc variable representing the current document. Modify doc fields to update the document. Return null or () to delete the document. To enable this feature: PATCH /experimental-features/ {"editDocumentsByFunction": true}.

filter · any

Filter expression to select which documents to edit. If omitted, all documents in the index will be processed. Attributes must be in filterableAttributes to be used.

context · any

Arbitrary data to pass into the function scope. By default the function only has access to the current document being edited via the doc variable.

Response

202

application/json

Task successfully enqueued.

A summarized view of a task, returned when a task is enqueued

taskUid · integer<u-int32> · required

Unique sequential identifier of the task.

Required range: x >= 0

status · enum<string> · required

Status of the task. Possible values are enqueued, processing, succeeded, failed, and canceled.

Available options: enqueued, processing, succeeded, failed, canceled

Example:

"processing"

type · enum<string> · required

Type of operation performed by the task.

Available options: documentAdditionOrUpdate, documentEdition, documentDeletion, settingsUpdate, indexCreation, indexDeletion, indexUpdate, indexSwap, taskCancelation, taskDeletion, dumpCreation, snapshotCreation, export, upgradeDatabase, indexCompaction, networkTopologyChange

Example:

"documentAdditionOrUpdate"

enqueuedAt · string<date-time> · required

Date and time when the task was enqueued.

indexUid · string | null

Unique identifier of the targeted index. Null for global tasks.

customMetadata · string | null

Custom metadata attached to this task at creation. Use it to associate tasks with external systems or add application-specific information.