Call an Atlas Function - Kotlin SDK

Overview

You can call an Atlas Function from a client application using the Realm Kotlin SDK. Functions are serverless JavaScript functions that let you define and execute server-side logic. These server-side Functions can run in the context of the authenticated user, and thus honor the rules, roles, and permissions that you have assigned to your data in Atlas.

You can serialize Function arguments and return values using an EJSON encoder. For more information, including examples, refer to EJSON Encoding for Atlas.

For more information on configuring and writing Atlas Functions, refer to Atlas Functions in the App Services documentation.

Before You Begin

1. In an App Services App, define an Atlas Function.

2. In your client project, initialize the App client.

3. Then, authenticate a user. Functions are accessed through the User object.

Call a Function

To call an Atlas Function from the Kotlin SDK, pass its name and all arguments to Functions.call().

Consider an Atlas Function running in an App Services App named sum that takes two arguments, adds them, and returns the result:

// Add two numbers
exports = function(a, b) {
   return a + b;
};

To call this Atlas Function from the Kotlin SDK:

runBlocking {
    val app: App = App.create(appID)
    val user = app.login(credentials)
    // Access the Atlas Function through the authenticated user
    // Pass the Function name and all arguments
    val response = user.functions.call<Int>("sum", 1, 2)
    print(response) // prints: 3
}

Limitations in Realm Kotlin SDK v1.8.x and Earlier

If you are using Kotlin SDK v1.9.0 or later, these limitations no longer apply.

Because the Kotlin serialization engine does not yet support third-party libraries, there are limitations to the types you can pass as arguments and the types you can deserialize the results to in a called Function.

You cannot pass objects as arguments.

The following are valid argument value types:

• Primitives

• Bson

• MutableRealmInt

• RealmUUID

• ObjectId

• RealmInstant

• RealmAny

• Array

• Collection (List or Set)

• Map

The following are valid return value types:

• Primitives

• Bson

• MutableRealmInt

• RealmUUID

• ObjectId

• RealmInstant

• RealmAny

• BsonArray (for Array and Collection argument types)

• BsonDocument (for Map argument types)