Push to Algolia connector

Use the Push to Algolia connector when your app controls which records to index and when to send them. Your app sends records to a connector task with an API client. Algolia transforms the records and writes them to the destination index. If Algolia can retrieve your data directly, use another connector. For example, use the JSON connector if your records are available as a hosted JSON file and you want Algolia to fetch them on demand or on a schedule without an indexing script. If your records don’t need an Algolia-managed transformation, send them directly with an API client.

Quickstart

Create a transformation, destination, and task for a public product dataset, then run a Node.js script that pushes the records through the connector. The script uses pushTask to identify the connector task explicitly by its task ID.

Before you begin

Make sure you have:

An Algolia account. Create one for free if you don’t already have one.
Node.js 22 or later and npm.
Your Algolia Write API key.
Your Algolia application’s analytics region: us for the United States or eu for Europe.

Set up the Push to Algolia connector

Open the Push to Algolia connector

Go to the Algolia dashboard and select your Algolia . On the left sidebar, select Data sources, then open the Connectors page.

Connect the source

Select Push to Algolia, then select Connect.

Transform the records

This transformation adds a price_range attribute to each record. After the connector indexes your records, you can display price_range or configure it as a facet.Select Transform using the code editor and replace the placeholder Transformation code with this function:

JavaScript

async function transform(record, helper) {
    const price = Number(record.price);

    if (!Number.isFinite(price)) {
    return record;
    }

    if (price < 25) {
    record.price_range = "Under $25";
    } else if (price < 50) {
    record.price_range = "$25 to $49";
    } else if (price < 100) {
    record.price_range = "$50 to $99";
    } else {
    record.price_range = "$100 and up";
    }

    return record;
}

Save the transformation.

Select index and credentials

Select Create a new destination to choose an for the connector to store records.Under Connect your data to Algolia Search, enter quickstart-products and, under Index credentials, select Create one for me.

Use a new index for this quickstart to avoid adding new records to it.

Create the destination

In Name, enter Quickstart push destination and select Create destination.

Create the task

Select Create task. The dashboard opens API Client & Code snippets with a generated pushTask example.Copy the taskID value from the example, then select Close.Continue with the next step instead of copying the generated records or code. The next steps use environment variables to keep your API key out of the source code.

Create a Node.js project

In a terminal, create a project and install the Algolia API client and dotenv:

Command line

mkdir algolia-push-quickstart
cd algolia-push-quickstart
npm init -y
npm install algoliasearch@5 dotenv

Add your Algolia credentials

Create a .env file in the project directory:

.env

ALGOLIA_APPLICATION_ID=
ALGOLIA_API_KEY=
ALGOLIA_APPLICATION_REGION=
ALGOLIA_TASK_ID=

Set the variables to your Algolia application ID, write API key, analytics region, and task ID.To keep your Write API key secret, create a .gitignore file in the project directory:

.gitignore

.env
node_modules/

Push the sample records

Create a push.mjs file with this code:

push.mjs

import "dotenv/config";
import { algoliasearch } from "algoliasearch";

const datasetUrl =
  "https://dashboard.algolia.com/api/1/sample_datasets?type=apparel";

async function main() {
  const {
    ALGOLIA_APPLICATION_ID: appId,
    ALGOLIA_API_KEY: apiKey,
    ALGOLIA_APPLICATION_REGION: region,
    ALGOLIA_TASK_ID: taskID,
  } = process.env;

  if (!appId || !apiKey || !region || !taskID) {
    throw new Error(
      "Set ALGOLIA_APPLICATION_ID, ALGOLIA_API_KEY, " +
        "ALGOLIA_APPLICATION_REGION, and ALGOLIA_TASK_ID in your .env file.",
    );
  }

  if (region !== "us" && region !== "eu") {
    throw new Error(
      "ALGOLIA_APPLICATION_REGION must be either 'us' or 'eu'.",
    );
  }

  const client = algoliasearch(appId, apiKey).initIngestion({ region });

  // Confirm that the task belongs to this application and region.
  await client.getTask({ taskID });

  const response = await fetch(datasetUrl);

  if (!response.ok) {
    throw new Error(
      `Couldn't fetch the sample dataset: ` +
        `${response.status} ${response.statusText}`,
    );
  }

  const products = await response.json();

  if (!Array.isArray(products)) {
    throw new Error("The sample dataset didn't return an array of records.");
  }

  const result = await client.pushTask({
    taskID,
    pushTaskPayload: {
      action: "addObject",
      records: products,
    },
    watch: true,
  });

  console.log(`Submitted ${products.length} records.`);
  console.log(`Run ID: ${result.runID}`);
}

main().catch((error) => {
  const message = error instanceof Error ? error.message : String(error);

  console.error(`Push failed: ${message}`);
  process.exitCode = 1;
});

Run the script:

Command line

node push.mjs

Copy the Run ID printed by the script.

Verify the indexing operation

Open the Connector Debugger and search for the run ID printed by push.mjs. Confirm that the operation completed successfully.Open the quickstart-products index in the Algolia dashboard. Confirm that it contains product records with attributes such as title, description, product_type, price, price_range, and showcase_image.

You can use this index as the data source for Build your first search experience. Before you start the UI steps in that quickstart, configure product_type as a facet for the quickstart-products index.

Use the connector with your app

In production, replace the quickstart data request in push.mjs with code that selects records from your app or data pipeline. For example, supply records from a processing job or a source for which Algolia doesn’t provide another connector.

Prepare your records

Send only the records required by the indexing operation. For example, your app can send a changed record after updating its source data instead of exporting and synchronizing the full dataset. Ensure each record has a stable, unique objectID. If your source uses a different unique property, map it before pushing the records:

JavaScript

const records = sourceRecords.map((record) => ({
  ...record,
  objectID: String(record.id),
}));

Update your transformation to match your record structure. If you want to make a transformed attribute searchable, use it for faceting, or use it for ranking, update the corresponding index setting: searchableAttributes, attributesForFaceting, or customRanking.

Choose an API client method

Choose a method based on how you want to identify the connector task and update the index.

Use case	Method
Target a specific connector task by its task ID	`pushTask`
Push one request by index name when one task matches	`push`
Push large record sets in batches, with control over the action and batch size	`chunkedPush`
Add or replace complete records by adapting an existing Search API implementation	`saveObjectsWithTransformation`
Add or update selected attributes by adapting an existing Search API implementation	`partialUpdateObjectsWithTransformation`
Replace every record in an index by adapting an existing Search API implementation	`replaceAllObjectsWithTransformation`

push, chunkedPush, and the WithTransformation helper methods select a user-created Push to Algolia task by index name. They support one user-created Push to Algolia connector, including when the index also uses Collections.
If multiple destinations link to the index or multiple user-created Push to Algolia connectors target it, use pushTask and specify the task ID. To send records through the Collections pipeline, use its task ID with pushTask.

Push with the Ingestion API

Use the Ingestion API client to choose the indexing action or identify a connector task by ID.

Push by task ID

Use pushTask to select a connector task by its task ID.

var response = await client.PushTaskAsync(
  "6c02aeb1-775e-418e-870b-1faccd4b2c0f",
  new PushTaskPayload
  {
    Action = Enum.Parse<Action>("AddObject"),
    Records = new List<PushTaskRecords>
    {
      new PushTaskRecords
      {
        ObjectID = "o",
        AdditionalProperties = new Dictionary<string, object>
        {
          { "key", "bar" },
          { "foo", "1" },
        },
      },
      new PushTaskRecords
      {
        ObjectID = "k",
        AdditionalProperties = new Dictionary<string, object>
        {
          { "key", "baz" },
          { "foo", "2" },
        },
      },
    },
  }
);

final response = await client.pushTask(
  taskID: "6c02aeb1-775e-418e-870b-1faccd4b2c0f",
  pushTaskPayload: PushTaskPayload(
    action: Action.fromJson("addObject"),
    records: [
      PushTaskRecords(
        objectID: "o",
        additionalProperties: {
          'key': "bar",
          'foo': "1",
        },
      ),
      PushTaskRecords(
        objectID: "k",
        additionalProperties: {
          'key': "baz",
          'foo': "2",
        },
      ),
    ],
  ),
);

response, err := client.PushTask(client.NewApiPushTaskRequest(
  "6c02aeb1-775e-418e-870b-1faccd4b2c0f",
  ingestion.NewEmptyPushTaskPayload().SetAction(ingestion.Action("addObject")).SetRecords(
    []ingestion.PushTaskRecords{
      *ingestion.NewEmptyPushTaskRecords().SetAdditionalProperty("key", "bar").SetAdditionalProperty("foo", "1").SetObjectID("o"),
      *ingestion.NewEmptyPushTaskRecords().SetAdditionalProperty("key", "baz").SetAdditionalProperty("foo", "2").SetObjectID("k"),
    }),
))
if err != nil {
  // handle the eventual error
  panic(err)
}

WatchResponse response = client.pushTask(
  "6c02aeb1-775e-418e-870b-1faccd4b2c0f",
  new PushTaskPayload()
    .setAction(Action.ADD_OBJECT)
    .setRecords(
      Arrays.asList(
        new PushTaskRecords().setAdditionalProperty("key", "bar").setAdditionalProperty("foo", "1").setObjectID("o"),
        new PushTaskRecords().setAdditionalProperty("key", "baz").setAdditionalProperty("foo", "2").setObjectID("k")
      )
    )
);

const response = await client.pushTask({
  taskID: '6c02aeb1-775e-418e-870b-1faccd4b2c0f',
  pushTaskPayload: {
    action: 'addObject',
    records: [
      { key: 'bar', foo: '1', objectID: 'o' },
      { key: 'baz', foo: '2', objectID: 'k' },
    ],
  },
});

var response =
  client.pushTask(
    taskID = "6c02aeb1-775e-418e-870b-1faccd4b2c0f",
    pushTaskPayload =
      PushTaskPayload(
        action = Action.entries.first { it.value == "addObject" },
        records =
          listOf(
            PushTaskRecords(
              objectID = "o",
              additionalProperties =
                mapOf("key" to JsonPrimitive("bar"), "foo" to JsonPrimitive("1")),
            ),
            PushTaskRecords(
              objectID = "k",
              additionalProperties =
                mapOf("key" to JsonPrimitive("baz"), "foo" to JsonPrimitive("2")),
            ),
          ),
      ),
  )

$response = $client->pushTask(
    '6c02aeb1-775e-418e-870b-1faccd4b2c0f',
    ['action' => 'addObject',
        'records' => [
            ['key' => 'bar',
                'foo' => '1',
                'objectID' => 'o',
            ],

            ['key' => 'baz',
                'foo' => '2',
                'objectID' => 'k',
            ],
        ],
    ],
);

response = client.push_task(
    task_id="6c02aeb1-775e-418e-870b-1faccd4b2c0f",
    push_task_payload={
        "action": "addObject",
        "records": [
            {
                "key": "bar",
                "foo": "1",
                "objectID": "o",
            },
            {
                "key": "baz",
                "foo": "2",
                "objectID": "k",
            },
        ],
    },
)

response = client.push_task(
  "6c02aeb1-775e-418e-870b-1faccd4b2c0f",
  Algolia::Ingestion::PushTaskPayload.new(
    action: "addObject",
    records: [
      Algolia::Ingestion::PushTaskRecords.new(key: "bar", foo: "1", algolia_object_id: "o"),
      Algolia::Ingestion::PushTaskRecords.new(key: "baz", foo: "2", algolia_object_id: "k")
    ]
  )
)

val response = Await.result(
  client.pushTask(
    taskID = "6c02aeb1-775e-418e-870b-1faccd4b2c0f",
    pushTaskPayload = PushTaskPayload(
      action = Action.withName("addObject"),
      records = Seq(
        PushTaskRecords(
          objectID = "o",
          additionalProperties = Some(List(JField("key", JString("bar")), JField("foo", JString("1"))))
        ),
        PushTaskRecords(
          objectID = "k",
          additionalProperties = Some(List(JField("key", JString("baz")), JField("foo", JString("2"))))
        )
      )
    )
  ),
  Duration(100, "sec")
)

let response = try await client.pushTask(
    taskID: "6c02aeb1-775e-418e-870b-1faccd4b2c0f",
    pushTaskPayload: PushTaskPayload(
        action: IngestionAction.addObject,
        records: [
            PushTaskRecords(from: [
                "objectID": AnyCodable("o"),
                "key": AnyCodable("bar"),
                "foo": AnyCodable("1"),
            ]),
            PushTaskRecords(from: [
                "objectID": AnyCodable("k"),
                "key": AnyCodable("baz"),
                "foo": AnyCodable("2"),
            ]),
        ]
    )
)

Push by index name

Use push when one task targets the specified index. The request returns an error if no task or more than one task matches the index name.

var response = await client.PushAsync(
  "INDEX_NAME",
  new PushTaskPayload
  {
    Action = Enum.Parse<Action>("AddObject"),
    Records = new List<PushTaskRecords>
    {
      new PushTaskRecords
      {
        ObjectID = "o",
        AdditionalProperties = new Dictionary<string, object>
        {
          { "key", "bar" },
          { "foo", "1" },
        },
      },
      new PushTaskRecords
      {
        ObjectID = "k",
        AdditionalProperties = new Dictionary<string, object>
        {
          { "key", "baz" },
          { "foo", "2" },
        },
      },
    },
  }
);

final response = await client.push(
  indexName: "INDEX_NAME",
  pushTaskPayload: PushTaskPayload(
    action: Action.fromJson("addObject"),
    records: [
      PushTaskRecords(
        objectID: "o",
        additionalProperties: {
          'key': "bar",
          'foo': "1",
        },
      ),
      PushTaskRecords(
        objectID: "k",
        additionalProperties: {
          'key': "baz",
          'foo': "2",
        },
      ),
    ],
  ),
);

response, err := client.Push(client.NewApiPushRequest(
  "INDEX_NAME",
  ingestion.NewEmptyPushTaskPayload().SetAction(ingestion.Action("addObject")).SetRecords(
    []ingestion.PushTaskRecords{
      *ingestion.NewEmptyPushTaskRecords().SetAdditionalProperty("key", "bar").SetAdditionalProperty("foo", "1").SetObjectID("o"),
      *ingestion.NewEmptyPushTaskRecords().SetAdditionalProperty("key", "baz").SetAdditionalProperty("foo", "2").SetObjectID("k"),
    }),
))
if err != nil {
  // handle the eventual error
  panic(err)
}

WatchResponse response = client.push(
  "INDEX_NAME",
  new PushTaskPayload()
    .setAction(Action.ADD_OBJECT)
    .setRecords(
      Arrays.asList(
        new PushTaskRecords().setAdditionalProperty("key", "bar").setAdditionalProperty("foo", "1").setObjectID("o"),
        new PushTaskRecords().setAdditionalProperty("key", "baz").setAdditionalProperty("foo", "2").setObjectID("k")
      )
    )
);

const response = await client.push({
  indexName: 'foo',
  pushTaskPayload: {
    action: 'addObject',
    records: [
      { key: 'bar', foo: '1', objectID: 'o' },
      { key: 'baz', foo: '2', objectID: 'k' },
    ],
  },
});

var response =
  client.push(
    indexName = "INDEX_NAME",
    pushTaskPayload =
      PushTaskPayload(
        action = Action.entries.first { it.value == "addObject" },
        records =
          listOf(
            PushTaskRecords(
              objectID = "o",
              additionalProperties =
                mapOf("key" to JsonPrimitive("bar"), "foo" to JsonPrimitive("1")),
            ),
            PushTaskRecords(
              objectID = "k",
              additionalProperties =
                mapOf("key" to JsonPrimitive("baz"), "foo" to JsonPrimitive("2")),
            ),
          ),
      ),
  )

$response = $client->push(
    'INDEX_NAME',
    ['action' => 'addObject',
        'records' => [
            ['key' => 'bar',
                'foo' => '1',
                'objectID' => 'o',
            ],

            ['key' => 'baz',
                'foo' => '2',
                'objectID' => 'k',
            ],
        ],
    ],
);

response = client.push(
    index_name="INDEX_NAME",
    push_task_payload={
        "action": "addObject",
        "records": [
            {
                "key": "bar",
                "foo": "1",
                "objectID": "o",
            },
            {
                "key": "baz",
                "foo": "2",
                "objectID": "k",
            },
        ],
    },
)

response = client.push(
  "INDEX_NAME",
  Algolia::Ingestion::PushTaskPayload.new(
    action: "addObject",
    records: [
      Algolia::Ingestion::PushTaskRecords.new(key: "bar", foo: "1", algolia_object_id: "o"),
      Algolia::Ingestion::PushTaskRecords.new(key: "baz", foo: "2", algolia_object_id: "k")
    ]
  )
)

val response = Await.result(
  client.push(
    indexName = "INDEX_NAME",
    pushTaskPayload = PushTaskPayload(
      action = Action.withName("addObject"),
      records = Seq(
        PushTaskRecords(
          objectID = "o",
          additionalProperties = Some(List(JField("key", JString("bar")), JField("foo", JString("1"))))
        ),
        PushTaskRecords(
          objectID = "k",
          additionalProperties = Some(List(JField("key", JString("baz")), JField("foo", JString("2"))))
        )
      )
    )
  ),
  Duration(100, "sec")
)

let response = try await client.push(
    indexName: "INDEX_NAME",
    pushTaskPayload: PushTaskPayload(
        action: IngestionAction.addObject,
        records: [
            PushTaskRecords(from: [
                "objectID": AnyCodable("o"),
                "key": AnyCodable("bar"),
                "foo": AnyCodable("1"),
            ]),
            PushTaskRecords(from: [
                "objectID": AnyCodable("k"),
                "key": AnyCodable("baz"),
                "foo": AnyCodable("2"),
            ]),
        ]
    )
)

Push records in batches

Use chunkedPush to split a large record set into batches and send each batch with push. The default batch size is 1,000 records. Use it directly when you need more control over the indexing action or batch size.

Search API `WithTransformation` methods

Use the Search API client helpers to adapt an existing implementation that calls saveObjects, partialUpdateObjects, or replaceAllObjects. The helpers route records through the Push to Algolia connector and automatically split them into batches. They’re subject to the connector limits. To run the examples, install the latest API client.

Set up transformation options

Before calling a WithTransformation method, configure transformationOptions with your Algolia application’s analytics region. The API client throws an error if you omit transformationOptions.

namespace Algolia;

using System;
using System.Collections.Generic;
using Algolia.Search.Clients;
using Algolia.Search.Http;
using Algolia.Search.Models.Search;

class SetUpTransformationOptions
{
  async Task Main(string[] args)
  {
    // Set TransformationOptions with your transformation region to use the `WithTransformation` helper methods.
    // Replace "us" with "eu" if your Algolia application uses the Europe analytics region.
    var client = SearchClient.WithTransformation(
      "ALGOLIA_APPLICATION_ID",
      "ALGOLIA_API_KEY",
      new TransformationOptions("us")
    );

    // Save records, transforming them through the Push connector
    try
    {
      var result = await client.SaveObjectsWithTransformationAsync(
        "INDEX_NAME",
        new List<Object>
        {
          new Dictionary<string, string> { { "objectID", "1" }, { "name", "Adam" } },
          new Dictionary<string, string> { { "objectID", "2" }, { "name", "Benoit" } },
        },
        true
      );
    }
    catch (Exception e)
    {
      Console.WriteLine(e.Message);
    }
  }
}

import 'package:algolia_client_search/algolia_client_search.dart';

void main() async {
  // Set transformationOptions with your transformation region to use the `WithTransformation` helper methods.
  // Replace 'us' with 'eu' if your Algolia application uses the Europe analytics region.
  final client = SearchClient(
    appId: 'ALGOLIA_APPLICATION_ID',
    apiKey: 'ALGOLIA_API_KEY',
    transformationOptions: TransformationOptions(region: 'us'),
  );

  try {
    // Save records, transforming them through the Push connector
    await client.saveObjectsWithTransformation(
      indexName: "INDEX_NAME",
      objects: [
        {
          'objectID': "1",
          'name': "Adam",
        },
        {
          'objectID': "2",
          'name': "Benoit",
        },
      ],
      waitForTasks: true,
    );
    print('Done!');
  } catch (e) {
    print('Error: ${e.toString()}');
  }
}

package main

import (
	"fmt"

	"github.com/algolia/algoliasearch-client-go/v4/algolia/search"
)

func setUpTransformationOptions() {
	// Set transformationOptions with your transformation region to use the `WithTransformation` helper methods.
	// Replace "us" with "eu" if your Algolia application uses the Europe analytics region.
	client, err := search.NewClient(
		"ALGOLIA_APPLICATION_ID",
		"ALGOLIA_API_KEY",
		search.WithTransformationOptions(search.TransformationOptions{Region: "us"}),
	)
	if err != nil {
		// The client can fail to initialize if you pass an invalid parameter.
		panic(err)
	}

	// Save records, transforming them through the Push connector
	result, err := client.SaveObjectsWithTransformation(
		"INDEX_NAME",
		[]map[string]any{{"objectID": "1", "name": "Adam"}, {"objectID": "2", "name": "Benoit"}}, search.WithWaitForTasks(true))
	if err != nil {
		panic(err)
	}

	fmt.Printf("Done! Uploaded records in %d batches.", len(result))
}

package com.algolia;

import com.algolia.api.SearchClient;
import com.algolia.config.*;
import com.algolia.model.search.*;
import java.util.Arrays;
import java.util.HashMap;

public class setUpTransformationOptions {

  public static void main(String[] args) throws Exception {
    // Set `transformationOptions` with your transformation region to use the `WithTransformation`
    // helper methods.
    // Replace "us" with "eu" if your Algolia application uses the Europe analytics region.
    SearchClient client = SearchClient.withTransformation("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", new TransformationOptions("us"));

    // Save records, transforming them through the Push connector
    client.saveObjectsWithTransformation(
      "INDEX_NAME",
      Arrays.asList(
        new HashMap() {
          {
            put("objectID", "1");
            put("name", "Adam");
          }
        },
        new HashMap() {
          {
            put("objectID", "2");
            put("name", "Benoit");
          }
        }
      ),
      true
    );
    client.close();
  }
}

import { algoliasearch } from 'algoliasearch';

// Set `transformationOptions` with your transformation region to use the `*WithTransformation` helper methods.
// Replace 'us' with 'eu' if your Algolia application uses the Europe analytics region.
const client = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY', {
  transformationOptions: { region: 'us' },
});

async function run() {
  // Save records, transforming them through the Push connector
  const response = await client.saveObjectsWithTransformation({
    indexName: 'INDEX_NAME',
    objects: [
      { objectID: '1', name: 'Adam' },
      { objectID: '2', name: 'Benoit' },
    ],
    waitForTasks: true,
  });
  console.log(response);
}

run().catch((err) => console.error(err));

package org.example

import com.algolia.client.api.SearchClient
import com.algolia.client.configuration.*
import com.algolia.client.extensions.*
import com.algolia.client.transport.*
import kotlinx.serialization.json.JsonPrimitive
import kotlinx.serialization.json.buildJsonObject

suspend fun main() {
  // Set `transformationOptions` with your transformation region to use the `WithTransformation`
  // helper methods.
  // Replace "us" with "eu" if your Algolia application uses the Europe analytics region.
  val client =
    SearchClient.withTransformation(
      appId = "ALGOLIA_APPLICATION_ID",
      apiKey = "ALGOLIA_API_KEY",
      transformationOptions = TransformationOptions(region = "us"),
    )

  try {
    // Save records, transforming them through the Push connector
    client.saveObjectsWithTransformation(
      indexName = "INDEX_NAME",
      objects =
        listOf(
          buildJsonObject {
            put("objectID", JsonPrimitive("1"))
            put("name", JsonPrimitive("Adam"))
          },
          buildJsonObject {
            put("objectID", JsonPrimitive("2"))
            put("name", JsonPrimitive("Benoit"))
          },
        ),
      waitForTasks = true,
    )
  } catch (e: Exception) {
    println(e.message)
  }
}

<?php

require __DIR__.'/../vendor/autoload.php';
use Algolia\AlgoliaSearch\Api\SearchClient;
use Algolia\AlgoliaSearch\Configuration\SearchConfig;
use Algolia\AlgoliaSearch\Configuration\TransformationOptions;

// Set transformationOptions with your transformation region to use the `WithTransformation` helper methods.
// Replace 'us' with 'eu' if your Algolia application uses the Europe analytics region.
$config = SearchConfig::create('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY');
$config->setTransformationOptions(new TransformationOptions('us'));
$client = SearchClient::createWithConfig($config);

// Save records, transforming them through the Push connector
$client->saveObjectsWithTransformation(
    'INDEX_NAME',
    [
        ['objectID' => '1',
            'name' => 'Adam',
        ],

        ['objectID' => '2',
            'name' => 'Benoit',
        ],
    ],
    true,
);

echo 'Done!';

from algoliasearch.search.client import SearchClientSync

from algoliasearch.search.config import SearchConfig, TransformationOptions


# Set `transformation_options` with your transformation region to use the `*_with_transformation` helper methods.
# Replace "us" with "eu" if your Algolia application uses the Europe analytics region.
_config = SearchConfig(
    "ALGOLIA_APPLICATION_ID",
    "ALGOLIA_API_KEY",
    transformation_options=TransformationOptions(region="us"),
)
_client = SearchClientSync.create_with_config(_config)

# Save records, transforming them through the Push connector
_client.save_objects_with_transformation(
    index_name="INDEX_NAME",
    objects=[
        {
            "objectID": "1",
            "name": "Adam",
        },
        {
            "objectID": "2",
            "name": "Benoit",
        },
    ],
    wait_for_tasks=True,
)

require "algolia"

# Set transformation options with your transformation region to use the `*_with_transformation` helper methods.
# Replace 'us' with 'eu' if your Algolia application uses the Europe analytics region.
client = Algolia::SearchClient.with_transformation(
  "ALGOLIA_APPLICATION_ID",
  "ALGOLIA_API_KEY",
  Algolia::TransformationOptions.new("us")
)

# Save records, transforming them through the Push connector
client.save_objects_with_transformation(
  "INDEX_NAME",
  [{objectID: "1", name: "Adam"}, {objectID: "2", name: "Benoit"}],
  true
)

puts("Done!")

import scala.concurrent.duration.Duration
import scala.concurrent.{Await, ExecutionContextExecutor}

import algoliasearch.api.SearchClient
import algoliasearch.config.*
import algoliasearch.extension.SearchClientExtensions
import org.json4s.*

object SetUpTransformationOptions {
  def main(args: Array[String]): Unit = {
    implicit val ec: ExecutionContextExecutor = scala.concurrent.ExecutionContext.global

    // Set transformationOptions with your transformation region to use the `WithTransformation` helper methods.
    // Replace "us" with "eu" if your Algolia application uses the Europe analytics region.
    val client = SearchClient.withTransformation(
      appId = "ALGOLIA_APPLICATION_ID",
      apiKey = "ALGOLIA_API_KEY",
      transformationOptions = TransformationOptions("us")
    )

    // Save records, transforming them through the Push connector
    try {
      Await.result(
        client.saveObjectsWithTransformation(
          indexName = "INDEX_NAME",
          objects = Seq(
            JObject(List(JField("objectID", JString("1")), JField("name", JString("Adam")))),
            JObject(List(JField("objectID", JString("2")), JField("name", JString("Benoit"))))
          ),
          waitForTasks = true
        ),
        Duration(100, "sec")
      )
    } catch {
      case e: Exception => println(e)
    }
  }
}

import Foundation
#if os(Linux) // For linux interop
    import FoundationNetworking
#endif

import AlgoliaCore
import AlgoliaSearch

func setUpTransformationOptions() async throws {
    // Set transformationOptions with your transformation region to use the `WithTransformation` helper methods.
    // Replace `.us` with `.eu` if your Algolia application uses the Europe analytics region.
    let configuration = try SearchClientConfiguration(
        appID: "ALGOLIA_APPLICATION_ID",
        apiKey: "ALGOLIA_API_KEY",
        transformationOptions: TransformationOptions(region: .us)
    )
    let client = SearchClient(configuration: configuration)

    do {
        // Save records, transforming them through the Push connector
        try await client.saveObjectsWithTransformation(
            indexName: "INDEX_NAME",
            objects: [["objectID": "1", "name": "Adam"], ["objectID": "2", "name": "Benoit"]],
            waitForTasks: true
        )
    } catch {
        print(error.localizedDescription)
    }
}

transformationOptions creates a dedicated ingestion transporter that starts from the Ingestion API defaults: 25-second timeouts, hosts derived from the region, and no compression. It only overrides the options you set and doesn’t inherit the Search API client’s configuration. For more information, see Transformation options and the ingestion transporter.

transformationOptions replaces the deprecated setTransformationRegion method in Java, C#, and PHP, the set_transformation_region method in Python, and the transformation option in JavaScript.

Add or replace records with a transformation

To add or replace complete records with a transformation, call saveObjectsWithTransformation.

var response = await client.SaveObjectsWithTransformationAsync(
  "INDEX_NAME",
  new List<Object>
  {
    new Dictionary<string, string> { { "objectID", "1" }, { "name", "Adam" } },
    new Dictionary<string, string> { { "objectID", "2" }, { "name", "Benoit" } },
  },
  true
);

final response = await client.saveObjectsWithTransformation(
  indexName: "INDEX_NAME",
  objects: [
    {
      'objectID': "1",
      'name': "Adam",
    },
    {
      'objectID': "2",
      'name': "Benoit",
    },
  ],
  waitForTasks: true,
);

response, err := client.SaveObjectsWithTransformation(
  "INDEX_NAME",
  []map[string]any{{"objectID": "1", "name": "Adam"}, {"objectID": "2", "name": "Benoit"}}, search.WithWaitForTasks(true))
if err != nil {
  // handle the eventual error
  panic(err)
}

List response = client.saveObjectsWithTransformation(
  "INDEX_NAME",
  Arrays.asList(
    new HashMap() {
      {
        put("objectID", "1");
        put("name", "Adam");
      }
    },
    new HashMap() {
      {
        put("objectID", "2");
        put("name", "Benoit");
      }
    }
  ),
  true
);

const response = await client.saveObjectsWithTransformation({
  indexName: 'cts_e2e_saveObjectsWithTransformation_javascript',
  objects: [
    { objectID: '1', name: 'Adam' },
    { objectID: '2', name: 'Benoit' },
  ],
  waitForTasks: true,
});

var response =
  client.saveObjectsWithTransformation(
    indexName = "INDEX_NAME",
    objects =
      listOf(
        buildJsonObject {
          put("objectID", JsonPrimitive("1"))
          put("name", JsonPrimitive("Adam"))
        },
        buildJsonObject {
          put("objectID", JsonPrimitive("2"))
          put("name", JsonPrimitive("Benoit"))
        },
      ),
    waitForTasks = true,
  )

$response = $client->saveObjectsWithTransformation(
    'INDEX_NAME',
    [
        ['objectID' => '1',
            'name' => 'Adam',
        ],

        ['objectID' => '2',
            'name' => 'Benoit',
        ],
    ],
    true,
);

response = client.save_objects_with_transformation(
    index_name="INDEX_NAME",
    objects=[
        {
            "objectID": "1",
            "name": "Adam",
        },
        {
            "objectID": "2",
            "name": "Benoit",
        },
    ],
    wait_for_tasks=True,
)

response = client.save_objects_with_transformation(
  "INDEX_NAME",
  [{objectID: "1", name: "Adam"}, {objectID: "2", name: "Benoit"}],
  true
)

val response = Await.result(
  client.saveObjectsWithTransformation(
    indexName = "INDEX_NAME",
    objects = Seq(
      JObject(List(JField("objectID", JString("1")), JField("name", JString("Adam")))),
      JObject(List(JField("objectID", JString("2")), JField("name", JString("Benoit"))))
    ),
    waitForTasks = true
  ),
  Duration(100, "sec")
)

let response = try await client.saveObjectsWithTransformation(
    indexName: "INDEX_NAME",
    objects: [["objectID": "1", "name": "Adam"], ["objectID": "2", "name": "Benoit"]],
    waitForTasks: true
)

Add or update record attributes with a transformation

To add or update selected attributes with a transformation, call partialUpdateObjectsWithTransformation.

var response = await client.PartialUpdateObjectsWithTransformationAsync(
  "INDEX_NAME",
  new List<Object>
  {
    new Dictionary<string, string> { { "objectID", "1" }, { "name", "Adam" } },
    new Dictionary<string, string> { { "objectID", "2" }, { "name", "Benoit" } },
  },
  true,
  true
);

final response = await client.partialUpdateObjectsWithTransformation(
  indexName: "INDEX_NAME",
  objects: [
    {
      'objectID': "1",
      'name': "Adam",
    },
    {
      'objectID': "2",
      'name': "Benoit",
    },
  ],
  createIfNotExists: true,
  waitForTasks: true,
);

response, err := client.PartialUpdateObjectsWithTransformation(
  "INDEX_NAME",
  []map[string]any{
    {"objectID": "1", "name": "Adam"},
    {"objectID": "2", "name": "Benoit"},
  },
  search.WithCreateIfNotExists(true),
  search.WithWaitForTasks(true),
)
if err != nil {
  // handle the eventual error
  panic(err)
}

List response = client.partialUpdateObjectsWithTransformation(
  "INDEX_NAME",
  Arrays.asList(
    new HashMap() {
      {
        put("objectID", "1");
        put("name", "Adam");
      }
    },
    new HashMap() {
      {
        put("objectID", "2");
        put("name", "Benoit");
      }
    }
  ),
  true,
  true
);

const response = await client.partialUpdateObjectsWithTransformation({
  indexName: 'cts_e2e_partialUpdateObjectsWithTransformation_javascript',
  objects: [
    { objectID: '1', name: 'Adam' },
    { objectID: '2', name: 'Benoit' },
  ],
  createIfNotExists: true,
  waitForTasks: true,
});

var response =
  client.partialUpdateObjectsWithTransformation(
    indexName = "INDEX_NAME",
    objects =
      listOf(
        buildJsonObject {
          put("objectID", JsonPrimitive("1"))
          put("name", JsonPrimitive("Adam"))
        },
        buildJsonObject {
          put("objectID", JsonPrimitive("2"))
          put("name", JsonPrimitive("Benoit"))
        },
      ),
    createIfNotExists = true,
    waitForTasks = true,
  )

$response = $client->partialUpdateObjectsWithTransformation(
    'INDEX_NAME',
    [
        ['objectID' => '1',
            'name' => 'Adam',
        ],

        ['objectID' => '2',
            'name' => 'Benoit',
        ],
    ],
    true,
    true,
);

response = client.partial_update_objects_with_transformation(
    index_name="INDEX_NAME",
    objects=[
        {
            "objectID": "1",
            "name": "Adam",
        },
        {
            "objectID": "2",
            "name": "Benoit",
        },
    ],
    create_if_not_exists=True,
    wait_for_tasks=True,
)

response = client.partial_update_objects_with_transformation(
  "INDEX_NAME",
  [{objectID: "1", name: "Adam"}, {objectID: "2", name: "Benoit"}],
  true,
  true
)

val response = Await.result(
  client.partialUpdateObjectsWithTransformation(
    indexName = "INDEX_NAME",
    objects = Seq(
      JObject(List(JField("objectID", JString("1")), JField("name", JString("Adam")))),
      JObject(List(JField("objectID", JString("2")), JField("name", JString("Benoit"))))
    ),
    createIfNotExists = true,
    waitForTasks = true
  ),
  Duration(100, "sec")
)

let response = try await client.partialUpdateObjectsWithTransformation(
    indexName: "INDEX_NAME",
    objects: [["objectID": "1", "name": "Adam"], ["objectID": "2", "name": "Benoit"]],
    createIfNotExists: true,
    waitForTasks: true
)

Replace all records with a transformation

To replace all records with a transformation, call replaceAllObjectsWithTransformation.

var response = await client.ReplaceAllObjectsWithTransformationAsync(
  "INDEX_NAME",
  new List<Object>
  {
    new Dictionary<string, string> { { "objectID", "1" }, { "name", "Adam" } },
    new Dictionary<string, string> { { "objectID", "2" }, { "name", "Benoit" } },
    new Dictionary<string, string> { { "objectID", "3" }, { "name", "Cyril" } },
    new Dictionary<string, string> { { "objectID", "4" }, { "name", "David" } },
    new Dictionary<string, string> { { "objectID", "5" }, { "name", "Eva" } },
    new Dictionary<string, string> { { "objectID", "6" }, { "name", "Fiona" } },
    new Dictionary<string, string> { { "objectID", "7" }, { "name", "Gael" } },
    new Dictionary<string, string> { { "objectID", "8" }, { "name", "Hugo" } },
    new Dictionary<string, string> { { "objectID", "9" }, { "name", "Igor" } },
    new Dictionary<string, string> { { "objectID", "10" }, { "name", "Julia" } },
  },
  3
);

final response = await client.replaceAllObjectsWithTransformation(
  indexName: "INDEX_NAME",
  objects: [
    {
      'objectID': "1",
      'name': "Adam",
    },
    {
      'objectID': "2",
      'name': "Benoit",
    },
    {
      'objectID': "3",
      'name': "Cyril",
    },
    {
      'objectID': "4",
      'name': "David",
    },
    {
      'objectID': "5",
      'name': "Eva",
    },
    {
      'objectID': "6",
      'name': "Fiona",
    },
    {
      'objectID': "7",
      'name': "Gael",
    },
    {
      'objectID': "8",
      'name': "Hugo",
    },
    {
      'objectID': "9",
      'name': "Igor",
    },
    {
      'objectID': "10",
      'name': "Julia",
    },
  ],
  batchSize: 3,
);

response, err := client.ReplaceAllObjectsWithTransformation(
  "INDEX_NAME",
  []map[string]any{
    {"objectID": "1", "name": "Adam"},
    {"objectID": "2", "name": "Benoit"},
    {"objectID": "3", "name": "Cyril"},
    {"objectID": "4", "name": "David"},
    {"objectID": "5", "name": "Eva"},
    {"objectID": "6", "name": "Fiona"},
    {"objectID": "7", "name": "Gael"},
    {"objectID": "8", "name": "Hugo"},
    {"objectID": "9", "name": "Igor"},
    {"objectID": "10", "name": "Julia"},
  },
  search.WithBatchSize(3),
)
if err != nil {
  // handle the eventual error
  panic(err)
}

ReplaceAllObjectsWithTransformationResponse response = client.replaceAllObjectsWithTransformation(
  "INDEX_NAME",
  Arrays.asList(
    new HashMap() {
      {
        put("objectID", "1");
        put("name", "Adam");
      }
    },
    new HashMap() {
      {
        put("objectID", "2");
        put("name", "Benoit");
      }
    },
    new HashMap() {
      {
        put("objectID", "3");
        put("name", "Cyril");
      }
    },
    new HashMap() {
      {
        put("objectID", "4");
        put("name", "David");
      }
    },
    new HashMap() {
      {
        put("objectID", "5");
        put("name", "Eva");
      }
    },
    new HashMap() {
      {
        put("objectID", "6");
        put("name", "Fiona");
      }
    },
    new HashMap() {
      {
        put("objectID", "7");
        put("name", "Gael");
      }
    },
    new HashMap() {
      {
        put("objectID", "8");
        put("name", "Hugo");
      }
    },
    new HashMap() {
      {
        put("objectID", "9");
        put("name", "Igor");
      }
    },
    new HashMap() {
      {
        put("objectID", "10");
        put("name", "Julia");
      }
    }
  ),
  3
);

const response = await client.replaceAllObjectsWithTransformation({
  indexName: 'cts_e2e_replace_all_objects_with_transformation_javascript',
  objects: [
    { objectID: '1', name: 'Adam' },
    { objectID: '2', name: 'Benoit' },
    { objectID: '3', name: 'Cyril' },
    { objectID: '4', name: 'David' },
    { objectID: '5', name: 'Eva' },
    { objectID: '6', name: 'Fiona' },
    { objectID: '7', name: 'Gael' },
    { objectID: '8', name: 'Hugo' },
    { objectID: '9', name: 'Igor' },
    { objectID: '10', name: 'Julia' },
  ],
  batchSize: 3,
});

var response =
  client.replaceAllObjectsWithTransformation(
    indexName = "INDEX_NAME",
    objects =
      listOf(
        buildJsonObject {
          put("objectID", JsonPrimitive("1"))
          put("name", JsonPrimitive("Adam"))
        },
        buildJsonObject {
          put("objectID", JsonPrimitive("2"))
          put("name", JsonPrimitive("Benoit"))
        },
        buildJsonObject {
          put("objectID", JsonPrimitive("3"))
          put("name", JsonPrimitive("Cyril"))
        },
        buildJsonObject {
          put("objectID", JsonPrimitive("4"))
          put("name", JsonPrimitive("David"))
        },
        buildJsonObject {
          put("objectID", JsonPrimitive("5"))
          put("name", JsonPrimitive("Eva"))
        },
        buildJsonObject {
          put("objectID", JsonPrimitive("6"))
          put("name", JsonPrimitive("Fiona"))
        },
        buildJsonObject {
          put("objectID", JsonPrimitive("7"))
          put("name", JsonPrimitive("Gael"))
        },
        buildJsonObject {
          put("objectID", JsonPrimitive("8"))
          put("name", JsonPrimitive("Hugo"))
        },
        buildJsonObject {
          put("objectID", JsonPrimitive("9"))
          put("name", JsonPrimitive("Igor"))
        },
        buildJsonObject {
          put("objectID", JsonPrimitive("10"))
          put("name", JsonPrimitive("Julia"))
        },
      ),
    batchSize = 3,
  )

$response = $client->replaceAllObjectsWithTransformation(
    'INDEX_NAME',
    [
        ['objectID' => '1',
            'name' => 'Adam',
        ],

        ['objectID' => '2',
            'name' => 'Benoit',
        ],

        ['objectID' => '3',
            'name' => 'Cyril',
        ],

        ['objectID' => '4',
            'name' => 'David',
        ],

        ['objectID' => '5',
            'name' => 'Eva',
        ],

        ['objectID' => '6',
            'name' => 'Fiona',
        ],

        ['objectID' => '7',
            'name' => 'Gael',
        ],

        ['objectID' => '8',
            'name' => 'Hugo',
        ],

        ['objectID' => '9',
            'name' => 'Igor',
        ],

        ['objectID' => '10',
            'name' => 'Julia',
        ],
    ],
    3,
);

response = client.replace_all_objects_with_transformation(
    index_name="INDEX_NAME",
    objects=[
        {
            "objectID": "1",
            "name": "Adam",
        },
        {
            "objectID": "2",
            "name": "Benoit",
        },
        {
            "objectID": "3",
            "name": "Cyril",
        },
        {
            "objectID": "4",
            "name": "David",
        },
        {
            "objectID": "5",
            "name": "Eva",
        },
        {
            "objectID": "6",
            "name": "Fiona",
        },
        {
            "objectID": "7",
            "name": "Gael",
        },
        {
            "objectID": "8",
            "name": "Hugo",
        },
        {
            "objectID": "9",
            "name": "Igor",
        },
        {
            "objectID": "10",
            "name": "Julia",
        },
    ],
    batch_size=3,
)

response = client.replace_all_objects_with_transformation(
  "INDEX_NAME",
  [
    {objectID: "1", name: "Adam"},
    {objectID: "2", name: "Benoit"},
    {objectID: "3", name: "Cyril"},
    {objectID: "4", name: "David"},
    {objectID: "5", name: "Eva"},
    {objectID: "6", name: "Fiona"},
    {objectID: "7", name: "Gael"},
    {objectID: "8", name: "Hugo"},
    {objectID: "9", name: "Igor"},
    {objectID: "10", name: "Julia"}
  ],
  3
)

val response = Await.result(
  client.replaceAllObjectsWithTransformation(
    indexName = "INDEX_NAME",
    objects = Seq(
      JObject(List(JField("objectID", JString("1")), JField("name", JString("Adam")))),
      JObject(List(JField("objectID", JString("2")), JField("name", JString("Benoit")))),
      JObject(List(JField("objectID", JString("3")), JField("name", JString("Cyril")))),
      JObject(List(JField("objectID", JString("4")), JField("name", JString("David")))),
      JObject(List(JField("objectID", JString("5")), JField("name", JString("Eva")))),
      JObject(List(JField("objectID", JString("6")), JField("name", JString("Fiona")))),
      JObject(List(JField("objectID", JString("7")), JField("name", JString("Gael")))),
      JObject(List(JField("objectID", JString("8")), JField("name", JString("Hugo")))),
      JObject(List(JField("objectID", JString("9")), JField("name", JString("Igor")))),
      JObject(List(JField("objectID", JString("10")), JField("name", JString("Julia"))))
    ),
    batchSize = 3
  ),
  Duration(100, "sec")
)

let response = try await client.replaceAllObjectsWithTransformation(
    indexName: "INDEX_NAME",
    objects: [
        ["objectID": "1", "name": "Adam"],
        ["objectID": "2", "name": "Benoit"],
        ["objectID": "3", "name": "Cyril"],
        ["objectID": "4", "name": "David"],
        ["objectID": "5", "name": "Eva"],
        ["objectID": "6", "name": "Fiona"],
        ["objectID": "7", "name": "Gael"],
        ["objectID": "8", "name": "Hugo"],
        ["objectID": "9", "name": "Igor"],
        ["objectID": "10", "name": "Julia"],
    ],
    batchSize: 3
)

Supported indexing actions

The Push to Algolia connector supports all values of the action property for batch indexing operations. For deleteObject, delete, and clear actions, the connector skips the transformation and uses traditional indexing.

Connector Debugger

To debug push operations:

Check incoming events in the Connector Debugger. The runID returned by a successful push or pushTask request identifies the indexing operation.
To wait for a push or pushTask operation and receive its result in the response, add the watch parameter. The response reports successful and failed operations.

Limitations

This connector is subject to the following limitations:

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Push to Algolia connector

Quickstart

Before you begin

Set up the Push to Algolia connector

Use the connector with your app

Prepare your records

Choose an API client method

Push with the Ingestion API

Push by task ID

Push by index name

Push records in batches

Search API `WithTransformation` methods

Set up transformation options

Add or replace records with a transformation

Add or update record attributes with a transformation

Replace all records with a transformation

Supported indexing actions

Connector Debugger

Limitations

See also

​Quickstart

​Before you begin

​Set up the Push to Algolia connector

​Use the connector with your app

​Prepare your records

​Choose an API client method

​Push with the Ingestion API

​Push by task ID

​Push by index name

​Push records in batches

​Search API WithTransformation methods

​Set up transformation options

​Add or replace records with a transformation

​Add or update record attributes with a transformation

​Replace all records with a transformation

​Supported indexing actions

​Connector Debugger

​Limitations

​See also

Quickstart

Before you begin

Set up the Push to Algolia connector

Use the connector with your app

Prepare your records

Choose an API client method

Push with the Ingestion API

Push by task ID

Push by index name

Push records in batches

Search API `WithTransformation` methods

Set up transformation options

Add or replace records with a transformation

Add or update record attributes with a transformation

Replace all records with a transformation

Supported indexing actions

Connector Debugger

Limitations

See also