Kotbase

https://kotbase.dev/current/
Admin
Kotbase is a Kotlin Multiplatform library that pairs Kotlin with Couchbase Lite for embedded NoSQL...
Tokens:67,053
Snippets:902
Trust Score:5.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Example App Output Log

Source: https://kotbase.dev/current/getting-started

This log output shows the typical sequence of events when the Kotbase Getting Started app runs, including database and collection creation, document operations, and retrieval.

```log
01-13 11:35:03.733 I/SHARED_KOTLIN: Database created: Database{@@0x9645222: 'desktopApp-db'}
01-13 11:35:03.742 I/SHARED_KOTLIN: Collection created: desktopApp-db@@x7fba7630dcb0._default.example-coll
01-13 11:35:03.764 I/DESKTOP_APP: Created document :: 83b6acb4-21ba-4834-aee4-2419dcea1114
01-13 11:35:03.767 I/SHARED_KOTLIN: Retrieved document:
01-13 11:35:03.767 I/SHARED_KOTLIN: Document ID :: 83b6acb4-21ba-4834-aee4-2419dcea1114
01-13 11:35:03.767 I/SHARED_KOTLIN: Learning :: Kotlin
01-13 11:35:03.768 I/DESKTOP_APP: Updated document :: 83b6acb4-21ba-4834-aee4-2419dcea1114
01-13 11:35:03.785 I/SHARED_KOTLIN: Number of rows :: 1
01-13 11:35:03.789 I/SHARED_KOTLIN: Document ID :: 83b6acb4-21ba-4834-aee4-2419dcea1114
01-13 11:35:03.790 I/SHARED_KOTLIN: Document :: {"language":"Kotlin","version":2.0,"platform":"JVM 21.0.1","input":"Hello, Kotbase!"}

```

--------------------------------

### Start Compose Multiplatform Android App

Source: https://kotbase.dev/current/getting-started

Execute this ADB command to start the main activity of the installed Android application built with Compose Multiplatform.

```bash
adb shell am start -n dev.kotbase.gettingstarted.compose/.MainActivity

```

--------------------------------

### Configure and Start Replicator

Source: https://kotbase.dev/current/integrate-custom-listener

Instantiate and start the Replicator using the configured MessageEndpoint and collections. The 'repl' object is stored for potential future use.

```kotlin
// Create the replicator object.
val repl = Replicator(
    ReplicatorConfiguration(messageEndpoint)
        .addCollections(collections)
)

// Start the replication.
repl.start()
this.replicator = repl

```

--------------------------------

### JOIN Statement Examples

Source: https://kotbase.dev/current/n1ql-query-strings

Examples of joining data sources using different operators and constraints.

```SQL
SELECT db.prop1, other.prop2 FROM db JOIN db AS other ON db.key = other.key

SELECT db.prop1, other.prop2 FROM db LEFT JOIN db other ON db.key = other.key

SELECT * FROM route r JOIN airline a ON r.airlineid = meta(a).id WHERE a.country = "France"
```

```SQL
SELECT * FROM travel-sample r JOIN travel-sample a ON r.airlineid = a.meta.id WHERE a.country = "France"
```

--------------------------------

### Run Android App via ADB

Source: https://kotbase.dev/current/getting-started

Execute this ADB command to start the main activity of the installed Android application.

```bash
adb shell am start -n dev.kotbase.gettingstarted/.MainActivity

```

--------------------------------

### Install Android App

Source: https://kotbase.dev/current/getting-started

Use this Gradle command to install the Android application in debug mode.

```bash
./gradlew :androidApp:installDebug

```

--------------------------------

### UNNEST Query Examples

Source: https://kotbase.dev/current/n1ql-query-strings

Examples demonstrating how to unpack nested arrays into individual rows for querying.

```JSON
{
  "Name": "Sam",
  "contacts": [
    {
      "type": "primary",
      "address": { "street": "1 St", "city": "San Pedro", "state": "CA" },
      "phones": [
        { "type": "home", "number": "310-123-4567" },
        { "type": "mobile", "number": "310-123-6789" }
      ]
    },
    {
      "type": "secondary",
      "address": { "street": "5 St", "city": "Seattle", "state": "WA" },
      "phones": [
        { "type": "home", "number": "206-123-4567" },
        { "type": "mobile", "number": "206-123-6789" }
      ]
    }
  ],
  "likes": ["soccer", "travel"]
}
```

```SQL
SELECT name, interest FROM _ UNNEST likes as interest WHERE interest = "travel"
```

```JSON
{ "name": "Sam", "like": "travel" }
```

```SQL
SELECT name, contact.type, phone.number
FROM profiles
UNNEST contacts as contact
UNNEST contact.phones as phone
WHERE phone.type = "mobile"
```

```JSON
{ "name": "Sam", "type": "primary", "number": "310-123-6789" }
{ "name": "Sam", "type": "secondary", "number": "206-123-6789" }
```

--------------------------------

### Install Couchbase Lite Meta Package with dpkg

Source: https://kotbase.dev/current/platforms

Install the downloaded Couchbase Lite meta package using 'sudo dpkg -i'. This is an alternative to 'apt install' for adding the package to your system.

```bash
sudo dpkg -i ./couchbase-release-1.0-noarch.deb
```

--------------------------------

### Install Couchbase Lite Meta Package with apt

Source: https://kotbase.dev/current/platforms

Install the downloaded Couchbase Lite meta package using 'sudo apt install'. This command ensures the package is correctly added to your system for APT to use.

```bash
sudo apt install ./couchbase-release-1.0-noarch.deb
```

--------------------------------

### SELECT Property Examples

Source: https://kotbase.dev/current/n1ql-query-strings

Various ways to project properties using the SELECT statement.

```sql
SELECT *

SELECT db.* AS data

SELECT name fullName

SELECT db.name fullName

SELECT DISTINCT address.city
```

--------------------------------

### Install Couchbase Lite Runtime Only

Source: https://kotbase.dev/current/platforms

Install the Couchbase Lite runtime package using 'sudo apt install libcblite'. This command installs the necessary components for running Couchbase Lite applications.

```bash
sudo apt install libcblite
```

--------------------------------

### Initialize and Start a Passive Peer Listener

Source: https://kotbase.dev/current/passive-peer

Configures a URLEndpointListener with specific collections, port, and authentication requirements before starting the service.

```kotlin
val listener = URLEndpointListener(
    URLEndpointListenerConfiguration(
        collections = collections,
        port = 55990,
        networkInterface = "wlan0",

        enableDeltaSync = false,

        // Configure server security
        disableTls = false,

        // Use an Anonymous Self-Signed Cert
        identity = null,

        // Configure Client Security using an Authenticator
        // For example, Basic Authentication
        authenticator = ListenerPasswordAuthenticator { usr, pwd ->
            (usr === validUser) && (pwd.concatToString() == validPass)
        }
    )
)

// Start the listener
listener.start()
```

--------------------------------

### FROM Clause Examples

Source: https://kotbase.dev/current/n1ql-query-strings

Demonstrates various ways to specify data sources, including aliases and the current database shorthand.

```SQL
SELECT name FROM db
SELECT name FROM scope.collection
SELECT store.name FROM db AS store
SELECT store.name FROM db store
SELECT name FROM _
SELECT store.name FROM _ AS store
SELECT store.name FROM _ store
```

--------------------------------

### Initialize and run replicator

Source: https://kotbase.dev/current/active-peer

Configures a Replicator with endpoint, authentication, and sync settings before starting the process.

```kotlin
// Create replicator
// Consider holding a reference somewhere
// to prevent the Replicator from being GCed
val repl = Replicator(
    // initialize the replicator configuration
    ReplicatorConfiguration(URLEndpoint("wss://listener.com:8954"))
        .addCollections(collections)
        .apply {
            // Set replicator type
            type = ReplicatorType.PUSH_AND_PULL

            // Configure Sync Mode
            isContinuous = false // default value

            // set auto-purge behavior
            // (here we override default)
            isAutoPurgeEnabled = false

            // Configure Server Authentication --
            // only accept self-signed certs
            isAcceptOnlySelfSignedServerCertificate = true

            // Configure the credentials the
            // client will provide if prompted
            authenticator = BasicAuthenticator("PRIVUSER", "let me in".toCharArray())
        }
)

// Start replicator
repl.start(false)

this.replicator = repl
this.token = token
```

--------------------------------

### Install Couchbase Lite Development Package

Source: https://kotbase.dev/current/platforms

Install the Couchbase Lite development package using 'sudo apt install libcblite-dev'. This includes headers and libraries needed for compiling applications that use Couchbase Lite.

```bash
sudo apt install libcblite-dev
```

--------------------------------

### Initialize and run replicator

Source: https://kotbase.dev/current/remote-sync-gateway

Initializes a Replicator with a specific configuration and starts it. Ensure a reference is held to prevent garbage collection.

```kotlin
// Create replicator
// Consider holding a reference somewhere
// to prevent the Replicator from being GCed
val repl = Replicator( 

    // initialize the replicator configuration
    ReplicatorConfiguration(URLEndpoint("wss://listener.com:8954"))
        .addCollections(collections)
        .apply {
            // Set replicator type
            type = ReplicatorType.PUSH_AND_PULL

            // Configure Sync Mode
            isContinuous = false // default value

            // set auto-purge behavior
            // (here we override default)
            isAutoPurgeEnabled = false

            // Configure Server Authentication --
            // only accept self-signed certs
            isAcceptOnlySelfSignedServerCertificate = true

            // Configure the credentials the
            // client will provide if prompted
            authenticator = BasicAuthenticator("PRIVUSER", "let me in".toCharArray())
        }
)

// Start replicator
repl.start(false)

this.replicator = repl
this.token = token
```

--------------------------------

### Install Couchbase Lite Community Runtime Only

Source: https://kotbase.dev/current/platforms

Install the Couchbase Lite Community Edition runtime package using 'sudo apt install libcblite-community'. This command installs the necessary components for running Couchbase Lite Community Edition applications.

```bash
sudo apt install libcblite-community
```

--------------------------------

### Install Compose Multiplatform Android App

Source: https://kotbase.dev/current/getting-started

Use this Gradle command to install the Android application built with Compose Multiplatform in debug mode.

```bash
./gradlew :composeApp:installDebug

```

--------------------------------

### JSON Result Format Examples

Source: https://kotbase.dev/current/query-result-sets

Examples of the JSON structure returned based on whether all properties or a subset are selected.

```json
{
  database-name: {
    key1: "value1",
    keyx: "valuex"
  }
}
```

```json
{
  key1: "value1",
  keyx: "valuex"
}
```

--------------------------------

### Query Output Example

Source: https://kotbase.dev/current/indexing

Expected output format for the UNNEST query.

```json
{ "name": "Sam", "like": "travel" }
```

--------------------------------

### Partial Index Query Examples

Source: https://kotbase.dev/current/indexing

Demonstrates queries that can and cannot utilize a partial index based on the WHERE clause.

```sql
SELECT * FROM col1 WHERE b=456 AND c<>0;  -- uses partial index
```

```sql
SELECT * FROM col1 WHERE b=456;  -- cannot use partial index
```

--------------------------------

### Collate Operator Examples

Source: https://kotbase.dev/current/n1ql-query-strings

Examples of applying different collation rules to string comparisons and ordering.

```SQL
SELECT department FROM db WHERE (name = "fred") COLLATE UNICODE
```

```SQL
SELECT department FROM db WHERE (name = "fred")
COLLATE (UNICODE)
```

```SQL
SELECT department FROM db WHERE (name = "fred") COLLATE (UNICODE CASE)
```

```SQL
SELECT name FROM db ORDER BY name COLLATE (UNICODE DIAC)
```

--------------------------------

### Data Model Example

Source: https://kotbase.dev/current/indexing

A sample JSON document structure representing a hotel entry.

```json
{
  "_id": "hotel123",
  "type": "hotel",
  "name": "The Michigander",
  "overview": "Ideally situated for exploration of the Motor City and the wider state of Michigan. Tripadvisor rated the hotel ...",
  "state": "Michigan"
}
```

--------------------------------

### Install Couchbase Lite Community Development Package

Source: https://kotbase.dev/current/platforms

Install the Couchbase Lite Community Edition development package using 'sudo apt install libcblite-dev-community'. This includes headers and libraries for compiling applications that use Couchbase Lite Community Edition.

```bash
sudo apt install libcblite-dev-community
```

--------------------------------

### Sample Document Structure

Source: https://kotbase.dev/current/indexing

Example JSON document containing nested arrays used for query demonstrations.

```json
{
  "Name": "Sam",
  "contacts": [
    {
      "type": "primary",
      "address": { "street": "1 St", "city": "San Pedro", "state": "CA" },
      "phones": [
        { "type": "home", "number": "310-123-4567" },
        { "type": "mobile", "number": "310-123-6789" }
      ]
    },
    {
      "type": "secondary",
      "address": { "street": "5 St", "city": "Seattle", "state": "WA" },
      "phones": [
        { "type": "home", "number": "206-123-4567" },
        { "type": "mobile", "number": "206-123-6789" }
      ]
    }
  ],
  "likes": ["soccer", "travel"]
}
```

--------------------------------

### Configure and Initialize Replicator

Source: https://kotbase.dev/current/active-peer

Initializes and configures a replicator for peer-to-peer synchronization. Ensure network and file I/O operations are performed on a background thread. This example configures basic authentication and accepts self-signed server certificates.

```kotlin
val repl = Replicator(
    // initialize the replicator configuration
    ReplicatorConfiguration(URLEndpoint("wss://listener.com:8954"))
        .addCollections(
            collections,
            CollectionConfiguration(
                conflictResolver = ReplicatorConfiguration.DEFAULT_CONFLICT_RESOLVER
            )
        ).apply {
            // Set replicator type
            type = ReplicatorType.PUSH_AND_PULL

            // Configure Sync Mode
            isContinuous = false // default value

            // Configure Server Authentication --
            // only accept self-signed certs
            isAcceptOnlySelfSignedServerCertificate = true

            // Configure the credentials the
            // client will provide if prompted
            authenticator = BasicAuthenticator("PRIVUSER", "let me in".toCharArray())
        }
)

// Optionally add a change listener
val token = repl.addChangeListener { change ->
    val err: CouchbaseLiteException? = change.status.error
    if (err != null) {
        println("Error code ::  ${err.code}\n$err")
    }
}

// Start replicator
repl.start(false)

this.replicator = repl
this.token = token
```

--------------------------------

### Install Kotbase Paging Community Edition

Source: https://kotbase.dev/current/paging

Add the Community Edition dependency to your build.gradle.kts file.

```kotlin
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("dev.kotbase:couchbase-lite-paging:3.2.4-1.2.0")
        }
    }
}
```

--------------------------------

### Install Kotbase Paging Enterprise Edition

Source: https://kotbase.dev/current/paging

Add the Enterprise Edition dependency to your build.gradle.kts file.

```kotlin
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("dev.kotbase:couchbase-lite-ee-paging:3.2.4-1.2.0")
        }
    }
}
```

--------------------------------

### Result Set Format for All Properties

Source: https://kotbase.dev/current/query-builder

Example structure of a result set returned by SelectResult.all().

```JSON
[
  {
    "travel-sample": { // The result for the first document matching the query criteria.
      "callsign": "MILE-AIR",
      "country": "United States",
      "iata": "Q5",
      "icao": "MLA",
      "id": 10,
      "name": "40-Mile Air",
      "type": "airline"
    }
  },
  {
    "travel-sample": { // The result for the next document matching the query criteria.
      "callsign": "ALASKAN-AIR",
      "country": "United States",
      "iata": "AA",
      "icao": "AAA",
      "id": 10,
      "name": "Alaskan Airways",
      "type": "airline"
    }
  }
]
```

--------------------------------

### Resetting checkpoints

Source: https://kotbase.dev/current/remote-sync-gateway

Forces the replication to start from zero by setting the reset option to true.

```kotlin
repl.start(true)
```

--------------------------------

### Install Vector Search for Java

Source: https://kotbase.dev/current/installation

Add the Vector Search library dependency to the jvmMain source set.

```kotlin
kotlin {
    sourceSets {
        ...
        jvmMain.dependencies {
            implementation("com.couchbase.lite:couchbase-lite-java-vector-search:1.0.0")
        }
    }
}
```

--------------------------------

### Implement Conflict Resolution Strategies

Source: https://kotbase.dev/current/handling-data-conflicts

Examples of defining local wins, remote wins, and merge conflict resolution strategies.

```kotlin
val localWinsResolver: ConflictResolver = { conflict ->
    conflict.localDocument
}
config.conflictResolver = localWinsResolver
```

```kotlin
val remoteWinsResolver: ConflictResolver = { conflict ->
    conflict.remoteDocument
}
config.conflictResolver = remoteWinsResolver
```

```kotlin
val mergeConflictResolver: ConflictResolver = { conflict ->
    val localDoc = conflict.localDocument?.toMap()?.toMutableMap()
    val remoteDoc = conflict.remoteDocument?.toMap()?.toMutableMap()

    val merge: MutableMap<String, Any?>?
    if (localDoc == null) {
        merge = remoteDoc
    } else {
        merge = localDoc
        if (remoteDoc != null) {
            merge.putAll(remoteDoc)
        }
    }

    if (merge == null) {
        MutableDocument(conflict.documentId)
    } else {
        MutableDocument(conflict.documentId, merge)
    }
}
config.conflictResolver = mergeConflictResolver
```

--------------------------------

### Build a Simple SELECT Query

Source: https://kotbase.dev/current/ktx

Use the QueryBuilder extensions for a more straightforward query syntax. This example selects all fields from a collection where the type is 'user'.

```kotlin
select(all()) from collection where { "type" equalTo "user" }

```

--------------------------------

### Query.explain() Output Example

Source: https://kotbase.dev/current/query-troubleshooting

The output from explain() includes the translated SQL query, the SQLite query plan, and the query in JSON-string format. The query plan is most useful for optimization.

```text
SELECT fl_result(fl_value(_doc.body, 'domains')) FROM kv_default AS _doc WHERE (_doc.flags & 1 = 0) GROUP BY fl_value(_doc.body, 'country') ORDER BY fl_value(_doc.body, 'country'), fl_value(_doc.body, 'name')

7|0|0| SCAN TABLE kv_default AS _doc
12|0|0| USE TEMP B-TREE FOR GROUP BY
52|0|0| USE TEMP B-TREE FOR ORDER BY

{"GROUP_BY":[[.".country"]],"ORDER_BY":[[.".country"],[.".name"]],"WHAT":[[.".domains"]]}

```

--------------------------------

### Dictionary Literal Syntax and Usage

Source: https://kotbase.dev/current/n1ql-query-strings

Defines the syntax for dictionary literals and provides examples of selecting dictionary data.

```SQL
dictionaryLiteral = '{' _ ( STRING_LITERAL ':' e:expression
  ( _ ',' _ STRING_LITERAL ':' _ expression )* )?
   '}'
```

```SQL
SELECT { 'name': 'James', 'department': 10 } FROM db
SELECT { 'name': 'James', 'department': dept } FROM db
SELECT { 'name': 'James', 'phones': ['650-100-1000', '650-100-2000'] } FROM db
```

--------------------------------

### Configure Push Filter for Replication

Source: https://kotbase.dev/current/remote-sync-gateway

Implement a push filter to control which documents are pushed to the server. This example filters out documents marked as DELETED.

```kotlin
val collectionConfig = CollectionConfiguration(
    pushFilter = { _, flags -> flags.contains(DocumentFlag.DELETED) }
)

// Create replicator (be sure to hold a reference somewhere that will prevent the Replicator from being GCed)
val repl = Replicator(
    ReplicatorConfiguration(URLEndpoint("ws://localhost:4984/mydatabase"))
        .addCollections(collections, collectionConfig)
)
repl.start()
this.replicator = repl
```

--------------------------------

### Open a Database and Get a Collection

Source: https://kotbase.dev/current/documents

Opens an existing database or creates a new one if it doesn't exist. It then retrieves a specific collection from the database. Ensure the collection exists or handle its absence.

```kotlin
val config = DatabaseConfiguration()
config.directory = "path/to/db"
val database = Database("getting-started", config)
val collection = database.getCollection("myCollection")
    ?: throw IllegalStateException("collection not found")
```

--------------------------------

### Set and Get Date Property

Source: https://kotbase.dev/current/documents

Store dates as ISO-8601 strings and use `Document.getDate()` to retrieve them. This example sets the `createdAt` property using `Clock.System.now()` and reads it back.

```kotlin
doc.setValue("createdAt", Clock.System.now())
val date = doc.getDate("createdAt")
```

--------------------------------

### Open or Create a Database with a Specific Directory

Source: https://kotbase.dev/current/databases

Use the Database class to open an existing database or create a new one. Specify the database name and optionally a DatabaseConfiguration, including the directory path. If the database does not exist, it will be created.

```kotlin
val database = Database(
    "my-db",
    DatabaseConfiguration()
        .setDirectory("path/to/database")
)

```

--------------------------------

### Wildcard Match with '%' in LIKE Expression

Source: https://kotbase.dev/current/query-builder

Use the '%' wildcard to match zero or more characters in a LIKE expression. This example searches for 'landmark' documents where the 'name' property starts with 'eng' followed by any characters, then 'e', then any characters. The search is case-insensitive.

```kotlin
val query = QueryBuilder
    .select(
        SelectResult.expression(Meta.id),
        SelectResult.property("country"),
        SelectResult.property("name")
    )
    .from(DataSource.collection(collection))
    .where(
        Expression.property("type").equalTo(Expression.string("landmark"))
            .and(
                Function.lower(Expression.property("name"))
                    .like(Expression.string("eng%e%"))
            )
    )
query.execute().use {
        it.forEach {
            println("name -> ${it.getString("name")}")
        }
    }
```

--------------------------------

### Wildcard Match with '_' in LIKE Expression

Source: https://kotbase.dev/current/query-builder

Use the '_' wildcard to match exactly one character in a LIKE expression. This example finds 'landmark' documents where the 'name' property starts with 'eng', followed by exactly four characters, and ends with 'r'. The search is case-insensitive.

```kotlin
val query = QueryBuilder
    .select(
        SelectResult.expression(Meta.id),
        SelectResult.property("country"),
        SelectResult.property("name")
    )
    .from(DataSource.collection(collection))
    .where(
        Expression.property("type").equalTo(Expression.string("landmark"))
            .and(
                Function.lower(Expression.property("name"))
                    .like(Expression.string("eng____r"))
            )
    )
query.execute().use {
        it.forEach {
            println("name -> ${it.getString("name")}")
        }
    }
```

--------------------------------

### Configure Server TLS Security

Source: https://kotbase.dev/current/active-peer

Examples for setting server certificate validation policies, including CA-attested, self-signed, and pinned certificate configurations.

```kotlin
// Configure Server Security
// -- only accept CA attested certs
acceptOnlySelfSignedServerCertificate = false,
```

```kotlin
// Configure Server Authentication --
// only accept self-signed certs
acceptOnlySelfSignedServerCertificate = true,
```

```kotlin
// Use the pinned certificate from the byte array (cert)
pinnedServerCertificate = TLSIdentity.getIdentity("Our Corporate Id")
    ?.certs?.firstOrNull()
    ?: throw IllegalStateException("Cannot find corporate id"),
```

--------------------------------

### Pattern Matching with REGEX Operator

Source: https://kotbase.dev/current/query-builder

Use the REGEX operator for pattern matching, similar to wildcards but more powerful. This example searches for 'landmark' documents where the 'name' property starts with 'eng' and ends with 'r', matching on word boundaries. Note that REGEX is case-sensitive by default.

```kotlin
val query = QueryBuilder
    .select(
        SelectResult.expression(Meta.id),
        SelectResult.property("country"),
        SelectResult.property("name")
    )
    .from(DataSource.collection(collection))
    .where(
        Expression.property("type").equalTo(Expression.string("landmark"))
            .and(
                Function.lower(Expression.property("name"))
                    .regex(Expression.string("\\beng.*r\\b"))
            )
    )
query.execute().use {
        it.forEach {
            println("name -> ${it.getString("name")}")
        }
    }
```

--------------------------------

### Query Plan Example

Source: https://kotbase.dev/current/query-troubleshooting

The query plan section shows how data will be retrieved and sorted. 'SCAN TABLE' indicates a full table scan, 'USE TEMP B-TREE FOR GROUP BY' and 'USE TEMP B-TREE FOR ORDER BY' suggest sorting operations.

```text
7|0|0| SCAN TABLE kv_default AS _doc
12|0|0| USE TEMP B-TREE FOR GROUP BY
52|0|0| USE TEMP B-TREE FOR ORDER BY

```

--------------------------------

### Download Couchbase Lite Meta Package with wget

Source: https://kotbase.dev/current/platforms

Use wget to download the Couchbase Lite meta package. This package is required for APT to manage Couchbase Lite installations.

```bash
wget https://packages.couchbase.com/releases/couchbase-release/couchbase-release-1.0-noarch.deb
```

--------------------------------

### Implement Basic Authentication

Source: https://kotbase.dev/current/remote-sync-gateway

Initiate replication using a username and password, which automatically retrieves a session cookie for subsequent requests.

```kotlin
// Create replicator (be sure to hold a reference somewhere that will prevent the Replicator from being GCed)
val repl = Replicator(
    ReplicatorConfiguration(URLEndpoint("ws://localhost:4984/mydatabase"))
        .addCollections(collections)
        .setAuthenticator(BasicAuthenticator("username", "password".toCharArray()))
)
repl.start()
this.replicator = repl
```

--------------------------------

### Run JVM Desktop App with Gradle

Source: https://kotbase.dev/current/getting-started

Execute the desktop application using the Gradle wrapper. Ensure you are in the project's root directory.

```bash
./gradlew :composeApp:run

```

--------------------------------

### Configure a Simple Replicator

Source: https://kotbase.dev/current/peer-to-peer-sync

Initializes a Replicator for bi-directional Peer-to-Peer synchronization with basic authentication and self-signed certificate acceptance.

```kotlin
val listenerEndpoint = URLEndpoint("wss://10.0.2.2:4984/db") 
val repl = Replicator(
    ReplicatorConfiguration(listenerEndpoint)
        .addCollections(collections)
        .apply {
            authenticator = BasicAuthenticator("valid.user", "valid.password.string".toCharArray())
            isAcceptOnlySelfSignedServerCertificate = true
        }
)
repl.start() 
this.replicator = repl
```

--------------------------------

### Initialize and Configure Replicator

Source: https://kotbase.dev/current/remote-sync-gateway

Configures a replicator with push/pull sync, authentication, and a change listener.

```kotlin
val repl = Replicator(
    // initialize the replicator configuration
    ReplicatorConfiguration(URLEndpoint("wss://listener.com:8954"))
        .addCollections(collections).apply {
            // Set replicator type
            type = ReplicatorType.PUSH_AND_PULL

            // Configure Sync Mode
            isContinuous = false // default value

            // set auto-purge behavior
            // (here we override default)
            isAutoPurgeEnabled = false

            // Configure Server Authentication --
            // only accept self-signed certs
            isAcceptOnlySelfSignedServerCertificate = true

            // Configure the credentials the
            // client will provide if prompted
            authenticator = BasicAuthenticator("PRIVUSER", "let me in".toCharArray())
        }
)

// Optionally add a change listener
val token = repl.addChangeListener { change ->
    val err: CouchbaseLiteException? = change.status.error
    if (err != null) {
        println("Error code ::  ${err.code}\n$err")
    }
}

// Start replicator
repl.start(false)

this.replicator = repl
this.token = token
```

--------------------------------

### Use Basic Authentication

Source: https://kotbase.dev/current/passive-peer

Configure password authentication for clients using username and password from the HTTP authentication header. Ensure the provided username and password match the server's valid credentials.

```kotlin
config.authenticator = ListenerPasswordAuthenticator {
    username, password ->
    username == validUser && password.concatToString() == validPassword
}
```

--------------------------------

### Configure a Simple Listener

Source: https://kotbase.dev/current/peer-to-peer-sync

Initializes a URLEndpointListener with password authentication to participate in encrypted synchronization.

```kotlin
val listener = URLEndpointListener(
    URLEndpointListenerConfiguration(
        collections = db.collections,
        authenticator = ListenerPasswordAuthenticator { user, pwd ->
            (user == "daniel") && (pwd.concatToString() == "123")
        }
    )
)
listener.start()
this.listener = listener
```

--------------------------------

### Logical Operators Usage

Source: https://kotbase.dev/current/n1ql-query-strings

Examples of using AND and OR operators within a WHERE clause.

```SQL
WHERE city = "San Francisco" AND status = true
```

```SQL
WHERE city = “San Francisco” OR city = "Santa Clara"
```

--------------------------------

### Unary Operators Usage

Source: https://kotbase.dev/current/n1ql-query-strings

Examples of using positive, negative, and logical NOT operators.

```SQL
WHERE v1 = +10
```

```SQL
WHERE v1 = -10
```

```SQL
WHERE "James" NOT IN contactsList
```

--------------------------------

### Prediction with Approx_Vector_Distance

Source: https://kotbase.dev/current/working-with-vector-search

Examples of using APPROX_VECTOR_DISTANCE() with vectors generated by the Prediction() function.

```APIDOC
## Prediction with `APPROX_VECTOR_DISTANCE()`

### Description
Below are examples of using `APPROX_VECTOR_DISTANCE()` with an array of vectors generated by the `Prediction()` function at index time.

### Method
SQL++ (Kotbase Query Language)

### Endpoint
N/A (In-memory query execution)

### Parameters
#### Query Parameters
- **vector** (Array<Float>) - Required - The target vector for comparison.

#### Request Body
N/A

### Request Example
```kotlin
// Create a vector search query that uses prediction() for computing vectors.
val sql = $$ """
    SELECT meta().id, color
    FROM _default.colors
    ORDER BY APPROX_VECTOR_DISTANCE(prediction(ColorModel, {"colorInput": color}).vector, $vector)
    LIMIT 8
""".trimIndent()

val query = database.createQuery(sql)

// Get a vector, an array of float numbers, for the input color code (e.g. FF000AA).
// Normally, you will get the vector from your ML model.
val vector = Color.getVector("FF00AA")
    ?: throw IllegalStateException("Vector not found")

// Set the vector array to the parameter "$vector"
val parameters = Parameters()
parameters.setValue("vector", vector)
query.parameters = parameters

// Execute the query
query.execute().use { rs ->
    // process results
}
```

### Response
#### Success Response (200)
- **id** (String) - The ID of the matching document.
- **color** (String) - The color field from the document.

#### Response Example
```json
{
  "id": "doc1",
  "color": "#FF00AA"
}
```
```

--------------------------------

### Initialize QueryPagingSource

Source: https://kotbase.dev/current/paging

Configure a QueryPagingSource with a data model, query mapper, and query provider.

```kotlin
// Uses kotlinx-serialization JSON processor
@Serializable
data class Hotel(val id: String, val type: String, val name: String)

val select = select(Meta.id, "type", "name")
val mapper = { json: String ->
    Json.decodeFromString<Hotel>(json)
}
val queryProvider: QueryProvider = {
    where {
        ("type" equalTo "hotel") and
        ("state" equalTo "California")
    }
    .orderBy { "name".ascending() }
}

val pagingSource = QueryPagingSource(
    EmptyCoroutineContext,
    select,
    collection,
    mapper,
    queryProvider
)
```

--------------------------------

### Searched Case Expression

Source: https://kotbase.dev/current/n1ql-query-strings

Example of a Searched CASE expression checking for non-null values.

```sql
SELECT CASE WHEN shippedOn IS NOT NULL THEN ‘SHIPPED’ ELSE "NOT-SHIPPED" END FROM db
```

--------------------------------

### Working with Blobs in Couchbase Lite

Source: https://kotbase.dev/current/blobs

Demonstrates creating a blob from a file source, adding it to a document, and retrieving the content as a byte array.

```kotlin
// kotlinx-io multiplatform file system APIs are still in development
// However, platform-specific implementations can be created in the meantime
expect fun getAsset(file: String): Source?

val mDoc = MutableDocument()

getAsset("avatar.jpg")?.use { source ->
  mDoc.setBlob("avatar", Blob("image/jpeg", source))
  collection.save(mDoc)
}

val doc = collection.getDocument(mDoc.id)
val bytes = doc?.getBlob("avatar")?.content
```

--------------------------------

### Simple Case Expression

Source: https://kotbase.dev/current/n1ql-query-strings

Example of a Simple CASE expression evaluating a state field.

```sql
SELECT CASE state WHEN ‘CA’ THEN ‘Local’ ELSE ‘Non-Local’ END FROM DB
```

--------------------------------

### Build a Complex Query with AND/OR and Ordering

Source: https://kotbase.dev/current/ktx

Demonstrates building a more complex query involving multiple conditions combined with AND/OR, ordering results, and limiting the output.

```kotlin
select("name", "type")
    .from(collection)
    .where {
        (("type" equalTo "user") and ("name" equalTo "Damian")) or
        (("type" equalTo "pet") and ("name" like "Kitt"))
    }
    .orderBy { "name".ascending() }
    .limit(10)

```

--------------------------------

### Idiomatic Mutable Dictionary Creation with KTX Extensions

Source: https://kotbase.dev/current/documents

Demonstrates an idiomatic way to create and populate a mutable dictionary using Kotbase KTX extensions, offering a more concise syntax.

```kotlin
val address = mutableDictOf(
    "street" to "1 Main st.",
    "city" to "San Francisco",
    "state" to "CA",
    "country" to "USA",
    "code" to "90210"
)
```

--------------------------------

### Return All Properties JSON Structure

Source: https://kotbase.dev/current/query-result-sets

Example of the JSON structure returned when using SelectResult.all().

```json
[
  {
    "travel-sample": { 
      "callsign": "MILE-AIR",
      "country": "United States",
      "iata": "Q5",
      "icao": "MLA",
      "id": 10,
      "name": "40-Mile Air",
      "type": "airline"
    }
  },
  {
    "travel-sample": { 
      "callsign": "ALASKAN-AIR",
      "country": "United States",
      "iata": "AA",
      "icao": "AAA",
      "id": 10,
      "name": "Alaskan Airways",
      "type": "airline"
    }
  }
]
```

--------------------------------

### URLEndpointListenerConfiguration

Source: https://kotbase.dev/current/peer-to-peer-sync

Configuration object for initializing the URLEndpointListener.

```APIDOC
## URLEndpointListenerConfiguration

Use `URLEndpointListenerConfiguration` to create a configuration object you can then use to initialize the listener.

### Properties

- **port** (integer) - Optional - The port that the listener will listen to. If the port is zero, the listener will auto-assign an available port. Default value is zero.
- **networkInterface** (string) - Optional - Selects a specific Network Interface to use, in the form of the IP Address or network interface name. If not specified, all available network interfaces will be used. The value is null if the listener is not started.
- **isTlsDisabled** (boolean) - Optional - Disables TLS communication if necessary. Default value is `false`. If `true`, TLS is disabled and `tlsIdentity` is ignored. Active peers use `ws://`. If `false`, TLS is enabled. Active peers use `wss://`.
- **tlsIdentity** (TLSIdentity) - Optional - Configures the TLS Identity used in TLS communication. If not set, an anonymous self-signed identity is auto-generated (unless `isTlsDisabled = true`). The identity is null when the listener is not started or when TLS is disabled.
- **authenticator** (Authenticator) - Optional - Specifies the authenticator the listener uses to authenticate the client’s connection request. Can be `ListenerPasswordAuthenticator`, `ListenerCertificateAuthenticator`, or `null` for no authentication.
- **isReadOnly** (boolean) - Optional - Allows only pull replication. Default value is `false`.
- **isDeltaSyncEnabled** (boolean) - Optional - Enables Delta Sync to replicate only changed data. Depends on delta sync settings at the database level. Default value is `false`.
```

--------------------------------

### ON KEYS JOIN Syntax

Source: https://kotbase.dev/current/n1ql-server-differences

Illustrates the difference in syntax for joining on keys using ON KEYS in Couchbase Server and a direct join on meta().id in Couchbase Lite.

```sql
SELECT * FROM `user` u
JOIN orders o ON KEYS ARRAY s.order_id
FOR s IN u.order_history END;
```

```sql
SELECT * FROM user u, u.order_history s
JOIN orders o ON s.order_id = meta(o).id;
```

--------------------------------

### String Concatenation Operator

Source: https://kotbase.dev/current/n1ql-query-strings

Example of using the || operator to concatenate strings in a SELECT statement.

```SQL
SELECT firstnm || lastnm AS fullname FROM db
```

--------------------------------

### Run JVM Desktop App

Source: https://kotbase.dev/current/getting-started

Use this Gradle command to run the JVM Desktop application.

```bash
./gradlew :desktopApp:run

```

--------------------------------

### Return Document ID JSON Structure

Source: https://kotbase.dev/current/query-result-sets

Example of the JSON structure returned when selecting Meta.id.

```json
[
  {
    "id": "hotel123"
  },
  {
    "id": "hotel456"
  }
]
```

--------------------------------

### Copy Pre-built Database on App Launch

Source: https://kotbase.dev/current/prebuilt-database

Use this snippet to copy a pre-built database if it doesn't exist. Ensure the `pathToPrebuiltDb` is correctly obtained and a `DatabaseConfiguration` is provided. This method generates a new UUID for the copied database.

```kotlin
if (Database.exists("travel-sample") {
    return
}
val pathToPrebuiltDb = getPrebuiltDbPathFromResources()
Database.copy(
    pathToPrebuiltDb,
    "travel-sample",
    DatabaseConfiguration()
)

```

--------------------------------

### LIMIT and OFFSET Statements

Source: https://kotbase.dev/current/n1ql-query-strings

Controls the number of results returned and the starting point of the result set.

```APIDOC
## LIMIT and OFFSET Statements

### Description
LIMIT specifies the maximum number of results to return. OFFSET specifies the number of results to skip before returning data.

### Syntax
`LIMIT expression`
`OFFSET expression`

### Request Example
`SELECT name FROM db LIMIT 10 OFFSET 10`
```

--------------------------------

### Run Native CLI App with Gradle

Source: https://kotbase.dev/current/getting-started

This Gradle command runs the native CLI application, passing input value and replication flag as properties.

```bash
./gradlew :cliApp:runDebugExecutableNative -PinputValue="" -Preplicate=false

```

--------------------------------

### ON KEY JOIN Syntax

Source: https://kotbase.dev/current/n1ql-server-differences

Compares the ON KEY JOIN syntax between Couchbase Server and Couchbase Lite, highlighting the use of meta() in Lite.

```sql
SELECT * FROM `user` u
JOIN orders o ON KEY o.user_id FOR u;
```

```sql
SELECT * FROM user u
JOIN orders o ON meta(u).id = o.user_id;
```

--------------------------------

### Implement MessageEndpointConnection.open

Source: https://kotbase.dev/current/integrate-custom-listener

Handles the opening of a connection by storing the ReplicatorConnection and invoking the completion handler.

```kotlin
/* implementation of MessageEndpointConnection */
override fun open(connection: ReplicatorConnection, completion: MessagingCompletion) {
    replicatorConnection = connection
    completion(true, null)
}
```

--------------------------------

### Parenthesis Expression Examples

Source: https://kotbase.dev/current/n1ql-query-strings

Use parenthesis to establish operator precedence and clarify conditional grouping in your queries.

```sql
SELECT (value1 + value2) * value 3
  FROM db
```

```sql
SELECT *
  FROM db
  WHERE ((value1 + value2) * value3) + value4 = 10
```

```sql
SELECT *
  FROM db
  -- Clarify the conditional grouping
  WHERE (value1 = value2)
     OR (value3 = value4)
```

--------------------------------

### Drop a Collection

Source: https://kotbase.dev/current/scopes-and-collections

Provides an example of how to delete a specific collection from a database using its name and scope name.

```kotlin
db.getCollection(collectionName, scopeName)?.let {
    db.deleteCollection(it.name, it.scope.name)
}

```

--------------------------------

### List Scopes and Collections

Source: https://kotbase.dev/current/scopes-and-collections

Demonstrates how to iterate through all scopes in a database and list the collections within each scope.

```kotlin
// List all of the collections in each of the scopes in the database
db.scopes.forEach { scope ->
    println("Scope :: ${scope.name}")
    scope.collections.forEach {
        println("    Collection :: ${it.name}")
    }
}

```

--------------------------------

### Install Kotbase Kermit Community Edition

Source: https://kotbase.dev/current/kermit

Add the Community Edition dependency to your commonMain source set in build.gradle.kts.

```kotlin
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("dev.kotbase:couchbase-lite-kermit:3.2.4-1.2.0")
        }
    }
}
```

--------------------------------

### Install Kotbase Kermit Enterprise Edition

Source: https://kotbase.dev/current/kermit

Add the Enterprise Edition dependency to your commonMain source set in build.gradle.kts.

```kotlin
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("dev.kotbase:couchbase-lite-ee-kermit:3.2.4-1.2.0")
        }
    }
}
```

--------------------------------

### Run Native CLI App Executable

Source: https://kotbase.dev/current/getting-started

Execute the built native CLI application with input value and replication flag as arguments.

```bash
cliApp/build/bin/native/debugExecutable/cliApp.kexe "<input value>" <true|false>

```

--------------------------------

### IN Operator Example

Source: https://kotbase.dev/current/n1ql-query-strings

The IN operator checks if a value exists within a specified list or array, returning TRUE if found.

```sql
WHERE "James" IN contactsList
```

--------------------------------

### Math Operators in WHERE Clause

Source: https://kotbase.dev/current/n1ql-query-strings

Examples of using mathematical operators (+, -, *, /, %) within a WHERE clause to filter data based on calculations.

```sql
WHERE v1 + v2 = 10
```

```sql
WHERE v1 - v2 = 10
```

```sql
WHERE v1 * v2 = 10
```

```sql
WHERE v1 / v2 = 10
```

```sql
WHERE v1 % v2 = 0
```

--------------------------------

### Array Literal Syntax and Usage

Source: https://kotbase.dev/current/n1ql-query-strings

Defines the syntax for array literals and provides examples of selecting array data.

```SQL
arrayLiteral = '[' _ (expression ( _ ',' _ e2:expression )* )? ']'
```

```SQL
SELECT ["a", "b", "c"] FROM _
SELECT [ property1, property2, property3] FROM _
```

--------------------------------

### Create FTS Index with SQL++

Source: https://kotbase.dev/current/full-text-search

Defines a full-text index on the 'overview' property using the FullTextIndexConfiguration object.

```kotlin
collection.createIndex(
    "overviewFTSIndex",
    FullTextIndexConfiguration("overview")
)
```

--------------------------------

### Return Specific Properties JSON Structure

Source: https://kotbase.dev/current/query-result-sets

Example of the JSON structure returned when selecting specific document properties.

```json
[
  { 
    "id": "hotel123",
    "type": "hotel",
    "name": "Hotel Ghia"
  },
  {
    "id": "hotel456",
    "type": "hotel",
    "name": "Hotel Deluxe",
  }
]
```

--------------------------------

### Configure Replicator with Conflict Resolver

Source: https://kotbase.dev/current/handling-data-conflicts

Register a custom conflict resolver within the ReplicatorConfiguration and start the replication process.

```kotlin
val collectionConfig = CollectionConfiguration(conflictResolver = localWinsResolver)
val repl = Replicator(
    ReplicatorConfiguration(URLEndpoint("ws://localhost:4984/mydatabase"))
        .addCollections(srcCollections, collectionConfig)
)

// Start the replicator
// (be sure to hold a reference somewhere that will prevent it from being GCed)
repl.start()
this.replicator = repl
```

--------------------------------

### Enable Delta Sync

Source: https://kotbase.dev/current/passive-peer

Configure delta sync for the listener to optimize bandwidth usage during replication.

```kotlin
enableDeltaSync = false,
```

--------------------------------

### Parenthesis Expressions

Source: https://kotbase.dev/current/n1ql-query-strings

Examples demonstrating the use of parenthesis to control operator precedence and clarify expression grouping in SQL queries.

```APIDOC
## Parenthesis Expressions

### Description
Parenthesis are used to establish operator precedence, ensuring that operations within the parenthesis are evaluated before others. This is crucial for complex calculations and conditional logic.

### Examples

```sql
-- Establish the desired operator precedence; do the addition before the multiplication
SELECT (value1 + value2) * value3
  FROM db

SELECT *
  FROM db
  WHERE ((value1 + value2) * value3) + value4 = 10

SELECT *
  FROM db
  -- Clarify the conditional grouping
  WHERE (value1 = value2)
     OR (value3 = value4)
```
```
Tokens:
Raw