Api clients / Ruby / V1 / Methods

Jan. 09, 2023

Partial Update Objects | Ruby API Client V1 (Deprecated)

This version of the Ruby API client has been deprecated in favor of the latest version of the Ruby API client.

Required API Key: any key with the addObject ACL

Method signature

index.partial_update_objects(objects)
index.partial_update_objects(
  Array objects,
  create_if_not_exists=Boolean,
  request_options=Hash
)

# update a single object
index.partial_update_object(Hash object)
index.partial_update_object(
  Hash object,
  objectID=Number,
  create_if_not_exists=Boolean,
  request_options=Hash
)

See code examples

About this method

Update one or more attributes of an existing object.

This method lets you update only a part of an existing object, either by adding new attributes or updating existing ones.

You can partially update several objects in a single method call.

When updating many or large objects, be aware of our rate limit.

Specifying existing attributes updates them in the object, while specifying new attributes adds them. You need to use the saveObjects method to completely redefine an existing object, or replace an object with a different one.

You can’t individually update nested attributes. Specifying a nested attribute treats it as a replacement of its first-level ancestor. To change nested attributes, you need to use the saveObjects method. You can retrieve the object’s data by using the getObjects method.

Built-in operations

For convenience, we provide five different built-in operations to update an attribute without pushing its entire value. These operations can be helpful if you don’t have access to your initial data.

Increment: increment a numeric attribute
Decrement: decrement a numeric attribute
Add: append a number or string element to an array attribute
Remove: remove all matching number or string elements from an array attribute
AddUnique: add a number or string element to an array attribute only if it’s not already present
IncrementFrom: increment a numeric integer attribute only if the provided value matches the current value, and otherwise ignore the whole object update. For example, if you pass an IncrementFrom value of 2 for the version attribute, but the current value of the attribute is 1, the engine ignores the update. If the object doesn’t exist, the engine only creates it if you pass an IncrementFrom value of 0.
IncrementSet : increment a numeric integer attribute only if the provided value is greater than the current value, and otherwise ignore the whole object update. For example, if you pass an IncrementSet value of 2 for the version attribute, and the current value of the attribute is 1, the engine updates the object. If the object doesn’t exist yet, the engine only creates it if you pass an IncrementSet value that’s greater than 0.

You can specify an operation by providing an object with two following properties:

_operation: the operation to apply on the attribute
value: the right-hand side argument to the operation (e.g., increment or decrement step, value to add or remove)

Only the IncrementFrom and IncrementSet operations guarantee idempotent record updates. The other built-in operations aren’t idempotent and can cause unexpected side-effects, unless you use them in combination with the idempotent operations. For example, if you’re using the Increment or Decrement operations in a concurrent or multi-threaded environment, you may trigger it more than once and end up with incorrect data in your records.

Note: This method also has a singular version.

Examples

Partially update multiple objects using one API call

Copy

1
2
3
4
5
6
7
8
9
10
11
12
$index->partialUpdateObjects(
    [
        [
            'objectID'  => 'myID1',
            'firstname' => 'Jimmie'
        ],
        [
            'objectID'  => 'myID2',
            'firstname' => 'Warren'
        ]
    ]
);

1
2
3
4
5
6
7
8
9
10
11
const objects = [{
  firstname: 'Jimmie',
  objectID: 'myID1'
}, {
  firstname: 'Warren',
  objectID: 'myID2'
}];

index.partialUpdateObjects(objects).then(({ objectIDs }) => {
  console.log(objectIDs);
});

1
2
3
4
5
6
7
8
9
10
let updates: [(ObjectID, PartialUpdate)] = [
  ("myID1", .update(attribute: "firstname", value: "Jimmie")),
  ("myID2", .update(attribute: "firstname", value: "Warren"))
]

index.partialUpdateObjects(updates: updates) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
List<JSONObject> array = new ArrayList<JSONObject>();

array.add(
  new JSONObject().put("firstname", "Jimmie").put("objectID", "myID")
);
array.add(
  new JSONObject().put("firstname", "Warren").put("objectID", "myID2")
);

index.partialUpdateObjectsAsync(new JSONArray(array), null);

1
2
3
4
5
6
7
8
9
10
List<Contact> contacts = new List<Contact>
{
    new Contact { ObjectID = "myID1", Firstname = "Jimmie" },
    new Contact { ObjectID = "myID2", Firstname = "Warren" }
};

index.PartialUpdateObjects(contacts);

// Asynchronous
await index.PartialUpdateObjectsAsync(contacts);

1
2
3
4
5
6
7
8
9
10
List<Contact> contacts = Arrays.asList(
  new Contact().setCity("San Francisco").setObjectID("MyID"),
  new Contact().setCity("Paris").setObjectID("MyID2")
);

// Sync version
index.partialUpdateObjects(contacts);

// Async version
index.partialUpdateObjectsAsync(contacts);

1
2
3
4
5
6
objects := []map[string]string{
  {"objectID": "myID1", "lastname": "Barninger"},
  {"objectID": "myID2", "firstname": "Ray"},
}

res, err := index.PartialUpdateObjects(objects)

1
2
3
4
5
6
7
val firstname = Attribute("firstname")
val partials = listOf(
    ObjectID("myID1") to Partial.Update(firstname, "Jimmie"),
    ObjectID("myID2") to Partial.Update(firstname, "Warren")
)

index.partialUpdateObjects(partials)

Partially update multiple objects using one API call and send extra HTTP headers

Copy

1
2
3
4
5
6
$objects = [/* objects */];

$res = $index->partialUpdateObjects($objects, [
  'createIfNotExists' => true,
  'X-Forwarded-For' => '94.228.178.246'
]);

1
2
3
4
5
6
7
8
9
objects = []

create_if_not_exits = true

extra_headers = {
  'X-Forwarded-For': '94.228.178.246'
}

res = index.partial_update_objects(objects, create_if_not_exits, extra_headers)

1
2
3
4
5
6
7
8
index.partialUpdateObjects(objects, {
  createIfNotExists: true,
  headers: {
    'X-Forwarded-For': '94.228.178.246'
  }
}).then(({ objectIDs }) => {
  console.log(objectIDs);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
var requestOptions = RequestOptions()
requestOptions.headers["X-Algolia-User-ID"] = "user123"

let updates: [(ObjectID, PartialUpdate)] = [
  ("myID1", .update(attribute: "firstname", value: "Jimmie")),
  ("myID2", .update(attribute: "firstname", value: "Warren"))
]

index.partialUpdateObjects(updates: updates, requestOptions: requestOptions) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
List<JSONObject> array = new ArrayList<JSONObject>();

array.add(
  new JSONObject().put("firstname", "Jimmie").put("objectID", "myID")
);
array.add(
  new JSONObject().put("firstname", "Warren").put("objectID", "myID2")
);
index.partialUpdateObjectsAsync(
  new JSONArray(array),
  true,
  new RequestOptions()
    .setHeader("X-Algolia-User-ID", "94.228.178.246"),
  null
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
List<Contact> contacts = new List<Contact>
{
    new Contact { ObjectID = "myID1", Firstname = "Jimmie" },
    new Contact { ObjectID = "myID2", Firstname = "Warren" }
};

RequestOptions requestOptions = new RequestOptions
{
    Headers = new Dictionary<string,string>{ { "X-Algolia-User-ID", "user123" } }
};

index.PartialUpdateObjects(contacts, requestOptions);

// Asynchronous
await index.PartialUpdateObjectsAsync(contacts, requestOptions);

1
2
3
4
5
6
7
8
9
10
11
12
13
List<Contact> contacts = Arrays.asList(
  new Contact().setCity("San Francisco").setObjectID("MyID"),
  new Contact().setCity("Paris").setObjectID("MyID2")
);

RequestOptions requestOptions =
    new RequestOptions().addExtraHeader("X-Algolia-User-ID", "user123")

// Sync version
index.partialUpdateObjects(contacts, requestOptions);

// Async version
index.partialUpdateObjectsAsync(contacts, requestOptions);

1
2
3
4
5
6
7
8
9
10
objects := []map[string]string{
  {"objectID": "myID1", "lastname": "Barninger"},
  {"objectID": "myID2", "firstname": "Ray"},
}

extraHeaders := opt.ExtraHeaders(map[string]string{
  "X-Algolia-User-ID": "userID2",
})

res, err := index.PartialUpdateObjects(objects, extraHeaders)

1
2
3
4
5
6
7
8
9
10
client.execute {
  client.execute {
    partialUpdate from "index" objects Seq(
      Contact("myID", "Jimmie", "Barninger"),
      Contact("myID", "Speach")
    ) options RequestOptions(
      extraHeaders = Some(Map("X-Algolia-User-ID" => "user123"))
    )
  }
}

1
2
3
4
5
6
7
8
9
10
val firstname = Attribute("firstname")
val partials = listOf(
    ObjectID("myID1") to Partial.Update(firstname, "Jimmie"),
    ObjectID("myID2") to Partial.Update(firstname, "Warren")
)
val requestOptions = requestOptions {
    headerAlgoliaUserId(UserID("user123"))
}

index.partialUpdateObjects(partials, requestOptions = requestOptions)

Update only the city attribute of an existing object

Copy

1
2
3
4
5
6
$index->partialUpdateObject(
  [
    'city'     => 'San Francisco',
    'objectID' => 'myID'
  ]
);

1
2
3
4
5
index.partialUpdateObject(withID: "myID", with: .update(attribute: "city", value: "San Francisco")) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
var contact = new Contact { ObjectID = "myID", City = "San Francisco"" };

index.PartialUpdateObject(contact);

// Asynchronous
await index.PartialUpdateObjectAsync(contact);

1
2
3
4
5
6
7
Contact contact = new Contact().setObjectID("myID").setCity("San Francisco");

// Sync version
index.partialUpdateObject(contact);

// Sync version
index.partialUpdateObjectAsync(contact);

1
2
3
4
5
6
7
8
9
10
11
type Contact struct {
	ObjectID string `json:"objectID"`
	City     string `json:"city"`
}

contact := Contact{
	ObjectID: "myID",
	City:     "San Francisco",
}

res, err := index.PartialUpdateObject(contact)

Add a new state attribute to an existing object

Copy

1
2
3
4
5
6
$index->partialUpdateObject(
  [
    'state'    => 'California',
    'objectID' => 'myID'
  ]
);

1
2
3
4
5
index.partialUpdateObject(withID: "myID", with: .update(attribute: "state", value: "California")) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
index.PartialUpdateObject(new Contact { ObjectID = "myID1", State = "California" });

// Asynchronous
await index.PartialUpdateObjectAsync(new Contact { ObjectID = "myID1", State = "California" });

1
2
3
4
5
6
7
Contact contact = new Contact().setObjectID("myID").setState("California");

// Sync version
index.partialUpdateObject(contact);

// Sync version
index.partialUpdateObjectAsync(contact);

1
2
3
4
5
6
7
8
9
10
11
type Contact struct {
	ObjectID string `json:"objectID"`
	State    string `json:"state"`
}

contact := Contact{
	ObjectID: "myID",
	State:    "California",
}

res, err := index.PartialUpdateObject(contact)

Increment an existing numeric attribute

Copy

1
2
3
4
5
6
7
8
9
$index->partialUpdateObject(
  [
    'count'    => [
      '_operation' => 'Increment',
      'value'      => 2
    ],
    'objectID' => 'myID'
  ]
);

1
2
3
4
5
6
7
8
9
10
index.partialUpdateObject({
  count: {
    _operation: 'Increment',
    value: 2,
  },
  objectID: 'myID',
})
.then(({ objectIDs }) => {
  console.log(objectIDs);
});

1
2
3
4
5
index.partialUpdateObject(withID: "myID", with: .increment(attribute: "count", value: 2)) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
class Record
{
    public string ObjectID { get; set; }

    public PartialUpdateOperation<int> Count { get; set; }
}

var record = new Record
{
    ObjectID = "myID",
    Count = PartialUpdateOperation<int>.Increment(2),
};

var res = index.PartialUpdateObjects(new List<Record>
{
    record
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
class RecordWithPartialUpdate {
    private String objectID;
    private PartialUpdateOperation<Integer> count;

    public Record(String objectID, PartialUpdateOperation<Integer> count) {
        this.objectID = objectID;
        this.count = count;
    }

    // Getters and setters omitted for readability
}

BatchIndexingResponse res = index.partialUpdateObjects(Collections.singletonList(
    new Record("myID", PartialUpdateOperation.Increment(2))
));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
type Record struct {
    ObjectID string                        `json:"objectID"`
    Count    search.PartialUpdateOperation `json:"count"`
}

res, err := index.PartialUpdateObjects([]Record{
    {
        ObjectID: "myID",
        Count: search.PartialUpdateOperation{
            Operation: "Increment",
            Value:     2,
        },
    },
})

Add a new value to an existing array attribute

Copy

1
2
3
4
5
6
7
8
9
$index->partialUpdateObject(
  [
    '_tags'    => [
      '_operation' => 'AddUnique',
      'value'      => 'public'
    ],
    'objectID' => 'myID'
  ]
);

1
2
3
4
5
6
7
8
9
10
index.partialUpdateObject({
  _tags: {
    _operation: 'AddUnique',
    value: 'public',
  },
  objectID: 'myID',
})
.then(({ objectIDs }) => {
  console.log(objectIDs);
});

1
2
3
4
5
index.partialUpdateObject(withID: "myID", with: .add(attribute: "_tags", value: "public", unique: true)) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
class Record
{
    public string ObjectID { get; set; }

    [JsonProperty(PropertyName = "_tags")]
    public PartialUpdateOperation<string> Tags { get; set; }
}

var record = new Record
{
    ObjectID = "myID",
    Tags = PartialUpdateOperation<string>.AddUnique("public"),
};

var res = index.PartialUpdateObjects(new List<Record>
{
    record
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
class RecordWithPartialUpdate {
    private String objectID;

    @JsonProperty("_tags")
    private PartialUpdateOperation<String> tags;

    public Record(String objectID, PartialUpdateOperation<String> tags) {
        this.objectID = objectID;
        this.tags = tags;
    }

    // Getters and setters omitted for readability
}

BatchIndexingResponse res = index.partialUpdateObjects(Collections.singletonList(
    new Record("myID", PartialUpdateOperation.AddUnique("public"))
));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
type Record struct {
    ObjectID string                        `json:"objectID"`
    Tags     search.PartialUpdateOperation `json:"_tags"`
}

res, err := index.PartialUpdateObjects([]Record{
    {
        ObjectID: "myID",
        Tags: search.PartialUpdateOperation{
            Operation: "AddUnique",
            Value:     "public",
        },
    },
})

Update only if the value matches a numeric attribute

Copy

1
2
3
4
5
6
7
8
9
$index->partialUpdateObject(
  [
    'version'    => [
      '_operation' => 'IncrementFrom',
      'value'      => 2
    ],
    'objectID' => 'myID'
  ]
);

1
2
3
4
5
6
7
8
9
10
index.partialUpdateObject({
  version: {
    _operation: 'IncrementFrom',
    value: 2,
  },
  objectID: 'myID',
})
.then(({ objectIDs }) => {
  console.log(objectIDs);
});

1
2
3
4
5
index.partialUpdateObject(withID: "myID", with: .incrementFrom(attribute: "version", value: 2)) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
class Record
{
    public string ObjectID { get; set; }

    public PartialUpdateOperation<int> Count { get; set; }
}

var record = new Record
{
    ObjectID = "myID",
    Count = PartialUpdateOperation<int>.IncrementFrom(2),
};

var res = index.PartialUpdateObjects(new List<Record>
{
    record
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
class RecordWithPartialUpdate {
    private String objectID;
    private PartialUpdateOperation<Integer> version;

    public Record(String objectID, PartialUpdateOperation<Integer> version) {
        this.objectID = objectID;
        this.version = version;
    }

    // Getters and setters omitted for readability
}

BatchIndexingResponse res = index.partialUpdateObjects(Collections.singletonList(
    new Record("myID", PartialUpdateOperation.incrementFrom(2))
));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
type Record struct {
    ObjectID string                        `json:"objectID"`
    Count    search.PartialUpdateOperation `json:"version"`
}

res, err := index.PartialUpdateObjects([]Record{
    {
        ObjectID: "myID",
        Count: search.PartialUpdateOperation{
            Operation: "IncrementFrom",
            Value:     2,
        },
    },
})

Update only if the value is greater than a numeric attribute

Copy

1
2
3
4
5
6
7
8
9
$index->partialUpdateObject(
  [
    'lastmodified'    => [
      '_operation' => 'IncrementSet',
      'value'      => 1593431913
    ],
    'objectID' => 'myID'
  ]
);

1
2
3
4
5
6
7
8
9
10
index.partialUpdateObject({
  lastmodified: {
    _operation: 'IncrementSet',
    value: 1593431913,
  },
  objectID: 'myID',
})
.then(({ objectIDs }) => {
  console.log(objectIDs);
});

1
2
3
4
5
index.partialUpdateObject(withID: "myID", with: .incrementSet(attribute: "lastmodified", value: 1593431913)) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
class Record
{
    public string ObjectID { get; set; }

    public PartialUpdateOperation<int> Count { get; set; }
}

var record = new Record
{
    ObjectID = "myID",
    Count = PartialUpdateOperation<int>.IncrementSet(1593431913),
};

var res = index.PartialUpdateObjects(new List<Record>
{
    record
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
class RecordWithPartialUpdate {
    private String objectID;
    private PartialUpdateOperation<Integer> lastmodified;

    public Record(String objectID, PartialUpdateOperation<Integer> lastmodified) {
        this.objectID = objectID;
        this.lastmodified = lastmodified;
    }

    // Getters and setters omitted for readability
}

BatchIndexingResponse res = index.partialUpdateObjects(Collections.singletonList(
    new Record("myID", PartialUpdateOperation.incrementSet(1593431913))
));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
type Record struct {
    ObjectID string                        `json:"objectID"`
    Count    search.PartialUpdateOperation `json:"lastmodified"`
}

res, err := index.PartialUpdateObjects([]Record{
    {
        ObjectID: "myID",
        Count: search.PartialUpdateOperation{
            Operation: "IncrementSet",
            Value:     1593431913,
        },
    },
})

Parameters

`objects`	type: list of object Required
`objectID`	type: integer Required objectID to update.
`createIfNotExists`	type: boolean default: true (false for .NET, Java, PHP and JavaScript) Optional When `true`, a partial update on a nonexistent object will create the object (generating the objectID and using the attributes as defined in the object). When `false`, a partial update on a nonexistent object will be ignored (but no error will be sent back). Note: Java, JavaScript, PHP and .NET default to `false`.
`requestOptions`	type: key/value mapping default: "" Optional A mapping of request options to send along with the query.

objects ➔ object

An object that matches part or all of your index’s object.

The object needs to contain an objectID.

If you supply an unknown objectID:

When <a href='#method-param-createifnotexists'>createIfNotExists</a> is true, the method creates a new record with the supplied objectID and attributes.
When <a href='#method-param-createifnotexists'>createIfNotExists</a> is false, the method ignores the new record (without sending back an error).

Response

In this section we document the JSON response returned by the API. Each language will encapsulate this response inside objects specific to the language and/or the implementation. So the actual type in your language might differ from what is documented.

JSON format

Copy

          {
  "objectIDs": [
    "myObjectID1",
    "myObjectID2"
  ],
  "taskID": 678,
}

        

`objectIDs`	list List of objectIDs of the objects to be updated.
`taskID`	integer The taskID used with the waitTask method.

Did you find this page helpful?

Partial Update Objects | Ruby API Client V1 (Deprecated)

About this method

Built-in operations

Examples

Partially update multiple objects using one API call

Partially update multiple objects using one API call and send extra HTTP headers

Update only the city attribute of an existing object

Add a new state attribute to an existing object

Increment an existing numeric attribute

Add a new value to an existing array attribute

Update only if the value matches a numeric attribute

Update only if the value is greater than a numeric attribute

Parameters

objects ➔ object

Response

JSON format

On this page