[0] Setup Guide

Setup Guide for DOPE Query Builder

Introduction

This guide outlines how to integrate the DOPE Query Builder into your Kotlin projects using either Gradle Kotlin DSL (build.gradle.kts) or Groovy DSL (build.gradle).

Prerequisites

Before you start, make sure you have the following ready:

• A Kotlin project setup within an IDE that supports Gradle (like IntelliJ IDEA).
• Java 17 or newer (DOPE is built and published for the JVM 17 toolchain).
• Basic knowledge of Gradle and your chosen DSL (Kotlin or Groovy).

Modules

DOPE is split into three published modules. Pick the ones you need:

Module	Purpose
core	The type-safe AST: clauses, expressions, operators, functions, and ValidTypes. Required for every project.
couchbase	The CouchbaseResolver that renders an AST into an N1QL/SQL++ query string. Also provides meta() and the Couchbase system keyspaces. Add this whenever you target Couchbase.
crystal-map-connector	Bridges crystal-map CMTypes into DOPE so schemas and fields can be used directly. Optional.

Adding DOPE to Your Project

Step 1: Configure the JitPack Repository

DOPE Query Builder is distributed through JitPack, which means you need to add JitPack as a repository to your project. This ensures that Gradle can fetch DOPE from the specified location.

For Gradle Kotlin DSL (build.gradle.kts):

repositories {
    mavenCentral()
    maven(url = "https://jitpack.io")
}

For Gradle Groovy DSL (build.gradle):

repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
}

Step 2: Add the Dependencies

Include the modules you need as dependencies. Replace <Version> with the latest JitPack version of DOPE:

For Gradle Kotlin DSL (build.gradle.kts):

dependencies {
    implementation("com.github.ergon.dope-query-builder:core:<Version>")
    implementation("com.github.ergon.dope-query-builder:couchbase:<Version>")
    // optional:
    implementation("com.github.ergon.dope-query-builder:crystal-map-connector:<Version>")
}

For Gradle Groovy DSL (build.gradle):

dependencies {
    implementation 'com.github.ergon.dope-query-builder:core:<Version>'
    implementation 'com.github.ergon.dope-query-builder:couchbase:<Version>'
    // optional:
    implementation 'com.github.ergon.dope-query-builder:crystal-map-connector:<Version>'
}

Step 3: Sync Your Project

After updating your build file, sync your project with Gradle to ensure all dependencies are properly downloaded. This can typically be done through your IDE or by running the following command in your terminal:

./gradlew --refresh-dependencies

Quickstart

import ch.ergon.dope.QueryBuilder
import ch.ergon.dope.couchbase.CouchbaseResolver
import ch.ergon.dope.resolvable.bucket.UnaliasedBucket
import ch.ergon.dope.resolvable.expression.type.Field
import ch.ergon.dope.validtype.NumberType
import ch.ergon.dope.validtype.StringType

val personBucket = UnaliasedBucket("person")
val personName = Field<StringType>(name = "name", path = "person")
val personAge = Field<NumberType>(name = "age", path = "person")

val query = QueryBuilder
    .select(personName, personAge)
    .from(personBucket)
    .where(personAge.isGreaterThan(18))
    .build(CouchbaseResolver())

// query.queryString  -> SELECT person.name, person.age FROM person WHERE person.age > 18
// query.parameters   -> DopeParameters(namedParameters = {...}, positionalParameters = [...])

QueryBuilder is a Kotlin object (singleton), so you call it without parentheses. .build(resolver) turns the AST into a concrete query: for Couchbase this is a CouchbaseDopeQuery exposing queryString and a DopeParameters value.