- Erfahren Sie, wie Sie Dokumente in Couchbase Lite mithilfe von SQL++ abfragen können.
- Use Live Queries with queryChangeFlow and Kotlin Co-Routine Flows using Live Data and Mutable Live Data
- Use JSON Serialization to “deserialize” documents from the database in to Kotlin data class
- Use indexes to speed up a query and try the count function with the QueryBuilder API
Einführung
Couchbase Mobile unterstützt SQL++-Abfragezeichenketten mithilfe der SQL++ Query API. SQL++ ist die deklarative Abfragesprache von Couchbase, die SQL für JSON erweitert. Die Struktur und die Semantik des Abfrageformats basieren auf der Abfragesprache SQL++ von Couchbase Server – siehe N1QL Referenzhandbuch und N1QL-Datenmodell.
In diesem Schritt des Lernpfads werden Sie die Grundlagen von:
- Abfragen mithilfe von SQL++ Strings
- Using Live Queries with queryChangeFlow and Kotlin Co-Routine Flows using Live Data and Mutable Live Data
- Using JSON Serialization to “deserialize” documents from the database in to Kotlin data class
- Verwendung von Indizes zur Beschleunigung einer Abfrage
- Using the count function with the QueryBuilder API
- Verwendung des Operators LIKE zur Suche nach Dokumenten mit einem bestimmten Wert in einem Feld
App-Übersicht
Obwohl die Demo-App viele Funktionen bietet, werden Sie in diesem Schritt Schritt für Schritt durch die folgenden Schritte geführt:
- Melden Sie sich in der Anwendung an
- Ein Projekt aus der Liste der Projekte auswählen
- Scrollen Sie durch die Liste der geprüften Lagerartikel
- Überprüfen Sie den Code zur Anzeige von geprüften Waren auf Lager
Hinweis: Dieser Schritt setzt voraus, dass Sie den vorherigen Schritt abgeschlossen haben.
Batch-VerfahrenDadurch wurden die Sampledaten in die Anwendung importiert. Dieser Teil des Lernpfads funktioniert nicht, wenn Sie die vorherigen Schritte nicht abgeschlossen haben.
Installation
App-Quellcode abrufen
Klonen von Quellcode
- If you haven’t already cloned the repo from the previous steps, clone the
Learn Couchbase Lite with Kotlin and Jetpack ComposeRepository von GitHub.
git clone https://github.com/couchbase-examples/android-kotlin-cbl-learning-path.git
Probieren Sie es aus
- Öffnen Sie mit Android Studio das Verzeichnis src/build.gradle.
- Das Projekt erstellen und ausführen.
- Melden Sie sich mit der App an “demo@example.com“ und “P@ssw0rd12” für die Felder „User-ID“ und „Passwort“ entsprechend.
- Vergewissern Sie sich, dass Sie Musterprojekte auf dem Bildschirm sehen. Wenn Sie auf ein Projekt tippen, werden die Konten für die Überprüfung des Inventars für dieses Projekt angezeigt.
- Wenn Sie keine Musterprojekte und Bestandsüberprüfungen sehen, füllen Sie bitte den vorherigen Schritt aus. Batch-Verfahren Um die Beispieldaten zu laden, bevor man fortfährt.

Das Prüfungsdokument
Die Beispiel-App wurde mit einer Sammlung von Dokument mit einem “Typ” Eigentum von “Audit” In den vorherigen Abschnitten des Lernpfads. Jedes Dokument repräsentiert einen Punkt, den ein Team notiert, wie viele dieser Elemente es im Lager während der Arbeit an einem Projekt gefunden hat.
Ein Beispiel für ein Dokument wäre:
{
"team": "team1",
"modifiedOn": "1656804470003",
"documentType": "audit",
"createdBy": "demo@example.com",
"modifiedBy": "demo@example.com",
"projectId": "c4a8fbac-083a-4ad5-87e5-2fe1c03a3689",
"createdOn": "1656804470003",
"auditId": "d3fb4d2e-0c75-4a85-b9b9-418a3b5f8303",
"notes": "Found item Langres Psion Ale - Sweet Ale with Langres flavors in warehouse",
"auditCount": 42330,
"stockItem": {
"name": "Langres Psion Ale",
"description": "Sweet Ale with Langres flavors",
"itemId": "e53dddf3-2058-4963-9293-66a87c84b29b",
"price": 52.76,
"style": "Imperial Stout"
}
}
Die Audit-Datenklasse
Wenn ein “Audit” Der Artikel wird aus der Datenbank abgerufen; er ist in einer Datenklasse des Typs „data“ gespeichert. Audit.
@Keep
@Serializable
@ExperimentalSerializationApi
data class Audit (
var auditId: String = "",
var projectId: String = "",
var stockItem: StockItem? = null,
var auditCount: Int = 0,
var documentType: String = "",
var notes: String = "",
//security tracking
var team: String = "",
var createdBy: String = "",
var modifiedBy: String = "",
@Serializable(with = DateSerializer::class)
var createdOn: Date? = null,
@Serializable(with = DateSerializer::class)
var modifiedOn: Date? = null
)
Die SQL++ Query String API mit der Count-Funktion erkunden
Die SQL++ Query String API in Couchbase Lite ist umfangreich. Auf dem Bildschirm „Entwickler – Datenbankinformationen“ werden die Anzahl der in der Inventardatenbank gefundenen Auditdokumente angezeigt. Die SQL++-Abfragezeichenfolge Für die Berechnung dieser Zahl wurde die API zusammen mit der Count-Funktion verwendet. Um den Entwicklerinformationsbildschirm anzuzeigen:
- Starten Sie die Invenory-Anwendung auf Ihrem Emulator.
- Login mit dem Benutzernamen demo@example.com und Passwort P@ssw0rd12
- Klicken Sie auf das Symbol des Schubladenmenüs (manchmal auch als „Hamburger“-Symbol bezeichnet) und tippen Sie auf „Entwickler“.
- Tippen Sie auf die Schaltfläche „Datenbankinformationen“
Zählung der Anzahl der Dokumente nach Typ
The “DevDatabaseInfoView” screen displays the count of how many documents are in the inventory database with the type set to ‘audit’.

The DevDatabaseInfoView function obtains this information from the DevDatabaseInfoViewModel class, which tracks this in a mutableStateOf variable. The view model calls the AuditRepositoryDb which runs the query to calculate the count.
private suspend fun updateAuditCount() {
viewModelScope.launch(Dispatchers.IO) {
val auditCount = auditRepository.count()
if (auditCount > 0) {
withContext(Dispatchers.Main) {
numberOfAudits.value = auditCount
}
}
}
}
- Öffnen Sie die AuditRepositoryDb.kt Datei öffnen und die
ZählenFunktion.
override suspend fun count(): Int {
- Wir erstellen die Abfrage mithilfe der
SQL++-AbfragezeichenfolgeAPI, der nach Dokumenten sucht, die den angegebenen Kriterien entsprechen.
var count = 0
try {
val db = DatabaseManager.getInstance(context).inventoryDatabase
db?.let { database ->
val query = database.createQuery("SELECT COUNT(*)
AS count FROM _ AS item WHERE
documentType="audit"") // 1
val results = query.execute().allResults() // 2
count = results[0].getInt("count") // 3
}
} catch (e: Exception) {
Log.e(e.message, e.stackTraceToString())
}
- Call the database API to create a Query using the createQuery function and passing in a string
- Wir führen die Abfrage durch, indem wir die
execute().allResults()method on the Query that was constructed in the previous step - Wir erhalten die Ergebnisse, indem wir das erste Ergebnis in der Sammlung betrachten und den Schlüssel “count”, den wir in der
SELECTKlausel
Weiterer Ausbau der SQL++ Query String API
Es gibt einige kleinere, aber bemerkenswerte Unterschiede in der Verhaltensweise zwischen SQL++ für Mobile-Anfragen und N1QL für Server. Weitere Informationen zu den Unterschieden finden Sie in der SQL++ Server-Unterschiede Dokumentation. In unserem Beispiel werden wir die API verwenden, um eine einfache Mustererkennung query using the equalTo operator. This example will use Live Query with Kotlin coroutine flows and live data.
Auditdokumente abrufen
Auf dem “Login”-Bildschirm wird einem Benutzer, wenn er sich mit den entsprechenden Zugangsdaten einloggt, eine Liste der Projekte angezeigt, an denen das Team arbeiten soll. Auf der Projektliste wird dem Benutzer eine Liste der Prüfungsnachweise angezeigt, die als Bestandsgegenstände an der Projektstandort platziert wurden.
-
Öffnen Sie die AuditListView.kt Datei öffnen und die
AuditListViewFunktion. -
The live query is converted from Live Data to state by calling the observeAsState function call on the Live Data list of audits provided by the view model.
val audits = viewModel.audits.observeAsState()
- To see how the live data list is created, open the AuditListViewModel.kt Datei öffnen und die
getAuditsFunktion.
viewModelScope.launch(Dispatchers.IO) {
_auditFlow = auditRepository.getAuditsByProjectId(project.projectId)
_auditFlow?.let { f ->
f.collect {
_audits.postValue(it)
}
}
}
-
The view model exposes the live data which is a list of audits from the repository getAuditsByProjectId function. Since the repository returns a flow the flow must be unboxed and then collected with the results added to the live data by calling the postValue function.
-
The getAuditsByProjectId function takes in the project’s projectId in order to filter out results to only the audits associated with that project.
-
To see how to build the flow, open the AuditRepositoryDb.kt file and locate the getAuditsByProjectId function.
override fun getAuditsByProjectId(projectId: String): Flow<List<Audit>>? {
- We first build a Query using the databases createQuery function that takes in a SQL++ query. Notice how parameter names start with a dollar sign and the dollar sign must be escaped with a .
val query = database.createQuery("SELECT * FROM _ AS item WHERE type="audit" AND projectId=$auditProjectId AND team=$auditTeam") // 1
val parameters = Parameters() // 2
parameters.setValue("auditProjectId", projectId) // 2
parameters.setValue("auditTeam", team) // 2
query.parameters = parameters // 3
val flow = query // 4
.queryChangeFlow() // 5
.map { qc -> mapQueryChangeToAudit(qc)} // 6
.flowOn(Dispatchers.IO) // 7
query.execute() // 8
return flow // 9
- Build a query using the databases
createQueryfunction - Erstellen Sie eine Parameter-Sammlung, in die die Parameter gespeichert werden sollen. Fügen Sie die Parameter und deren Werte in die Sammlung ein.
- Set the query parameters property to the parameter collection.
- Define a flow
- Use the queryChangeFlow function to return a flow
- Die intermediate operator map is used to change the results coming back using the mapQueryChangeToAudit function passing in the QueryChange. This is used to deserialize the results from JSON to the Audit data class.
- The flowOn function is used to make sure that the flow runs on the Dispatcher.IO context to keep the code from running on the main UI thread.
- The query executes. Remember this step MUST be done before returning the flow.
- Return the flow
REMINDER: Kotlin Co Routine Flows emit new values into the stream of data and are not returned until they are collected.
Indexieren der Abfrage
-
Die Erstellung von Indizes für nicht-FTS-basierte Abfragen ist optional. Um Abfragen zu beschleunigen, können Sie jedoch Indizes für die Eigenschaften erstellen, auf die Sie abfragen möchten. Die Indexierung wird aktiv durchgeführt.
-
In dem DatabaseManager.kt Datei, suchen Sie die
createAuditIndexFunktion. -
Wir erstellen einen Index auf der
Typ,projectIdundTeamEigenschaften der Dokumente in der Bestandsaufnahme Datenbank.
private fun createAuditIndex(){
try {
inventoryDatabase?.let { // 1
if (!it.indexes.contains(auditIndexName)) {
// create index for Audits to return documents with
// the type attribute set to audit, the projectId filtered
// by value sent in using equals, and the team attribute filtered
// by the value sent in using equals
it.createIndex( // 3
auditIndexName, // 4
IndexBuilder.valueIndex( // 5
ValueIndexItem.property(typeAttributeName), // 5
ValueIndexItem.property(projectIdAttributeName), // 5
ValueIndexItem.property(teamAttributeName)) // 5
)
}
}
} catch (e: Exception){
android.util.Log.e(e.message, e.stackTraceToString())
}
}
- The let keyword is used to unbox the database since it can be null.
- Call the database createIndex function which takes in a name of the index and then the properites to index
- The name of the index in string format. auditIndexName is defined toward the top of the class with the value
idxAudit - The IndexBuilder’s valueIndex function can be used to create the index
- The ValueIndexItem.property factory method can be used to create a ValueIndexItem by passing in the property of which to index.
SQL++ Query String API – Suche nach Lagerartikeln mit dem LIKE-Operator
Die SQL++-Abfrage-String-API unterstützt mehrere Operatoren, darunter den LIKE-Operator, der zur String-Übereinstimmung verwendet werden kann. Auf dem Dateneditor-Bildschirm verwenden wir den LIKE-Operator, um bei Audits nach einem Lagerbestand zu suchen, den wir in die Audits einfügen möchten. Laten Sie uns den Code überprüfen.
HinweisDer Gleicheinheitsoperator führt auch geschwindigkeitsabhängige Übereinstimmungen aus. Um geschwindigkeitsunabhängige Übereinstimmungen zu erzielen, verwenden Sie Klein- oder Großbuchstabenfunktionen, um sicherzustellen, dass alle Vergleichswerte denselben Buchstaben haben und damit das Problem des Buchstabenbedarfs beseitigt wird.
Auf dem Bildschirm „Audit-Editor“ bieten wir einen Link zur Seite „Aktienartikel“ an. Um den Bildschirm „Audit-Editor“ anzuzeigen:
- Starten Sie die Invenory-Anwendung auf Ihrem Emulator.
- Login mit dem Benutzernamen demo@example.com und Passwort P@ssw0rd12
- Tippen Sie auf eines der Projekte, um den Bildschirm „Revisionsliste“ anzuzeigen.
- Tippen Sie auf die + Schaltfläche, um eine neue Überprüfung hinzuzufügen.
- Tippen Sie auf die Schaltfläche
No Stock Item Selected

- Geben Sie im Feld „Name“ ipa ein.
- In the Description box enter wicked
- Klicken Sie auf die Schaltfläche „Suchen“
- Eine Liste der verfügbaren Artikel sollte diese Ergebnisse wiedergeben.

Lassen Sie uns den Code für den Bildschirm „Artikelbestand“ überprüfen.
Auswahl der Lagerartikel
-
Öffnen Sie die StockItemSelectionView.kt Datei öffnen und die
StockItemSelectionViewFunktion. -
The StockItemSelectionView exposes the viewModel’s onSearch which the StockItemSelector function uses with the Search button.
StockItemSelector(
searchName = viewModel.searchName.value,
searchDescription = viewModel.searchDescription.value,
onSearchNameChanged = viewModel.onSearchNameChanged,
onSearchDescriptionChanged = viewModel.onSearchDescriptionChanged,
onSearch = viewModel.onSearch,
stockItemStatusMessage = viewModel.statusMessage.value,
stockItems = viewModel.stockItemsState,
onStockItemSelected = onStockItemSelected
)
- This is defined as OnSearch in the StockItemSelector function
fun StockItemSelector(
searchName: String,
searchDescription: String,
onSearchNameChanged: (String) -> Unit,
onSearchDescriptionChanged: (String) -> Unit,
onSearch: () -> Unit,
stockItemStatusMessage: String,
stockItems: List<StockItem>,
onStockItemSelected: (StockItem) -> Unit)
- The search button then calls the OnSearch method on the OnClick listener.
Button(modifier = Modifier
.padding(top = 4.dp),
colors = ButtonDefaults.buttonColors(backgroundColor = Red500),
onClick = {
onSearch()
})
- Öffnen Sie die StockItemSelectionViewModel.kt Datei öffnen und die
onSearchval definition.
val onSearch: () -> Unit = {
viewModelScope.launch { // <1>
if (searchName.value.length >= 2) { // <2>
isLoading.value = true
val foundItems = stockItemRepository
.getByNameDescription(searchName.value, searchDescription.value) // <3>
if (foundItems.isNotEmpty()) { // <4>
withContext(Dispatchers.Main) {
stockItemsState.clear()
stockItemsState.addAll(foundItems)
isLoading.value = false
}
} else { // <5>
withContext(Dispatchers.Main) {
stockItemsState.clear()
statusMessage.value = "No stock items Found"
isLoading.value = false
}
}
}
}
}
- Since we will be talking to the database using suspend functions, we want to make sure we use viewModel Scope
- Business logic to check if the searchName value is greater than or equal to 2 characters. If so, then we can search for stock items.
- Call the stockItemRepository getByNameDescription function which takes in the searchName and searchDescription values.
- If the stock item list is not empty, then we can set the stockItemsState to the stock item list.
- If not, then we set the statusMessage to “No stock items Found”.
- Öffnen Sie die StockItemRepositoryDb.kt Datei öffnen und die
getByNameDescriptionFunktion.
override suspend fun getByNameDescription(
searchName: String,
searchDescription: String?
): List<StockItem> {
- We wil use withContext(Dispatchers.IO) to make sure we are working on the IO thread since we will be talking to the database.
val stockItems = mutableListOf<StockItem>()
try {
val db = databaseResources.warehouseDatabase
db?.let { database ->
var queryString = "SELECT * FROM _ as item WHERE
documentType="item" AND lower(name) LIKE ('%' ||
$parameterName || '%')" // 1
var parameters = Parameters() // 2
parameters.setString("parameterName", searchName.lowercase()) // 3
searchDescription?.let { description ->
if (description.isNotEmpty()) { // 4
queryString =
queryString.plus(" AND lower(description) LIKE ('%' || $parameterDescription || '%')") // 5
parameters.setString(
"parameterDescription",
searchDescription.lowercase()
) // 6
}
var query = database.createQuery(queryString) // 7
query.parameters = parameters // 8
var results = query.execute().allResults() // 9
results.forEach { result -> // 10
val stockItem = Json.decodeFromString<StockItemDao>(result.toJSON()).item // 11
stockItems.add(stockItem) // 12
}
}
}
} catch (e: java.lang.Exception) {
Log.e(e.message, e.stackTraceToString())
}
- Create a SQL++ query off the name attribute and use the like function with a defined parameter labeled parameterName. This is used to stop SQL injection bugs.
- Create a Parameters object.
- Add the parameterName to the Parameters object using the searchName varible passed in and making sure it’s lowercase.
- If the searchDescrpition value is not null
- We append the query and add the like function to the query filtering out the description attribute using the parameterDescription label.
- Add the parameterDescription to the Parameters object using the searchDescription varible passed in and making sure it’s lowercase.
- Create a query using the queryString
- Add the parameters to the query
- Excute the query using the Query API to select all the results
- Loop through all the results found in the database
- Decode the result to a StockItemDao object and set it to the stockItem variable
- Add the stockItem to the stockItems list
Mehr erfahren
Herzlichen Glückwunsch zu diesem Schritt auf unserem Lernweg!
This step of the learning path walked you through the SQL++ Query API in Couchbase Lite and used it to return documents from the database using serveral methods. Check out the following links for further documenation and continue on to the next step to learn more about how to setup Couchbase Server and Sync Gateway with Docker and Docker Compose.
Hinweise
- Dokumentation: SQL++-Abfragezeichenketten
- Dokumentation: SQL++-Abfragezeichenfolgen – Vergleichsoperatoren
- Dokumentation: SQL++-Abfragezeichenfolgen – Funktionen
- Dokumentation: SQL++-Unterschiede
- Dokumentation: Ergebnissets
- Dokumentation: Live-Abfrage – Arbeiten mit Abfragen
- Dokumentation: Abfragen und Fehlerbehebung