SDK
SDK Jvm v1.x
2

upsert #

Available since Kuzzle 2.8.0
Available since 1.2.1

Applies partial changes to a document. If the document doesn't already exist, a new document is created.

:::: tabs ::: tab Java

Copied to clipboard!
  public CompletableFuture<Map<String, Object>> upsert(
    String index,
    String collection,
    Map<String, Object> changes) throws NotConnectedException, InternalException

  public CompletableFuture<Map<String, Object>> upsert(
    String index,
    String collection,
    Map<String, Object> changes,
    Map<String, Object> defaults) throws NotConnectedException, InternalException

  public CompletableFuture<Map<String, Object>> upsert(
    String index,
    String collection,
    Map<String, Object> changes,
    Map<String, Object> defaults,
    Boolean waitForRefresh) throws NotConnectedException, InternalException
  
  public CompletableFuture<Map<String, Object>> upsert(
    String index,
    String collection,
    Map<String, Object> changes,
    Map<String, Object> defaults,
    Boolean waitForRefresh,
    Integer retryOnConflict) throws NotConnectedException, InternalException
  
  public CompletableFuture<Map<String, Object>> upsert(
    String index,
    String collection,
    Map<String, Object> changes,
    Map<String, Object> defaults,
    Boolean waitForRefresh,
    Integer retryOnConflict,
    Boolean source) throws NotConnectedException, InternalException
Argument Type Description
index
String
Index name
collection
String
Collection name
id
String
Document ID
changes
Map<String, Object>
Partial content of the document to update

Options #

Additional query options

Options Type
(default)
Description
defaults
Map<String, Object>

({})
Fields to add to the document if it gets created
waitForRefresh
Boolean

("")
If set to true, waits for the change to be reflected for search (up to 1s)
retryOnConflict
Integer

(10)
The number of times the database layer should retry in case of version conflict
source
Boolean

(false)
If true, returns the updated document inside the response

Returns #

A Map<String, Object> with the following properties:

Property Type Description
_source
Map<String, Object>
Updated document (if source option set to true)
_id
String
ID of the updated document
_version
Integer
Version of the document in the persistent data storage
created
Boolean

Usage #

Copied to clipboard!
Map<String, Object> category = new HashMap<>();
Map<String, Object> changes = new HashMap<>();
category.put("category", "suv");
changes.put("changes", category);
Map<String, Object> result = kuzzle
  .getDocumentController()
  .upsert("nyc-open-data", "yellow-taxi", "some-id", changes)
  .get();
/*
{
  created=true
  _id="some_id",
  version=1
}
*/

::: ::: tab Kotlin

Copied to clipboard!
fun upsert(
  index: String,
  collection: String,
  id: String,
  changes: Map<String, Any?>,
  defaults: Map<String, Any?>,
  waitForRefresh: Boolean? = null,
  retryOnConflict: Int? = null,
  source: Boolean? = null): CompletableFuture<Map<String, Any?>>
Argument Type Description
index
String
Index name
collection
String
Collection name
id
String
Document ID
changes
Map<String, Any?>
Partial content of the document to update

Options #

Additional query options

Options Type
(default)
Description
defaults
Map<String, Any?>

({})
Fields to add to the document if it gets created
waitForRefresh
Boolean

("")
If set to true, waits for the change to be reflected for search (up to 1s)
retryOnConflict
Integer

(10)
The number of times the database layer should retry in case of version conflict
source
Boolean

(false)
If true, returns the updated document inside the response

Returns #

A Map<String, Any?> object, with the following properties:

Property Type Description
_source
Map<String, Any?>
Updated document (if source option set to true)
_id
String
ID of the updated document
_version
Integer
Version of the document in the persistent data storage
created
Boolean

Usage #

Copied to clipboard!
val category: Map<String, Any?> =
  HashMap<String, Any?>().apply {
    put("category", "suv")
  }
val changes: Map<String, Any?> =
  HashMap<String, Any?>().apply {
    put("changes", category)  
  }
val result: Map<String, Any?> =
  kuzzle
    .documentController
    .upsert("nyc-open-data", "yellow-taxi", "some-id", changes)
    .get()

::: ::::