Skip to content

docs: 0.21.0 train — engine 0.21.0, extensions 0.3.0, drivers 0.3.0 #243

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fupelaqu merged 3 commits into from
Aug 20, 2026
+370 −109
Merged

docs: 0.21.0 train — engine 0.21.0, extensions 0.3.0, drivers 0.3.0 #243

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3a816d7
fix(installer): repair five Windows installer defects (#233-#237)
fupelaqu Aug 20, 2026
ecb9730
docs: 0.21.0 train -- engine 0.21.0, extensions 0.3.0, drivers 0.3.0
fupelaqu Aug 20, 2026
99e67d1
docs(sql): PARTITION BY, not PARTITIONED BY
fupelaqu Aug 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ curl -fsSL https://raw.githubusercontent.com/SOFTNETWORK-APP/SoftClient4ES/main/
irm https://raw.githubusercontent.com/SOFTNETWORK-APP/SoftClient4ES/main/install.ps1 | iex
```

**Windows (cmd.exe, when `.ps1` files are blocked):** one file — it fetches `install.ps1` if it is not beside it, takes the same flags, and only launches it with `-ExecutionPolicy Bypass`, for that one process.
**Windows (cmd.exe, when `.ps1` files are blocked):** one file — it fetches `install.ps1` if it is not beside it (from a pinned release tag, SHA-256 verified), takes the same flags, and only launches it with `-ExecutionPolicy Bypass`, for that one process.
```bat
curl -O https://raw.githubusercontent.com/SOFTNETWORK-APP/SoftClient4ES/main/install.cmd && install.cmd
```
Expand Down Expand Up @@ -216,10 +216,10 @@ Download the self-contained fat JAR for your Elasticsearch version:

| Elasticsearch Version | Artifact |
|-----------------------|----------------------------------------|
| ES 6.x | `softclient4es6-jdbc-driver-0.2.5.jar` |
| ES 7.x | `softclient4es7-jdbc-driver-0.2.5.jar` |
| ES 8.x | `softclient4es8-jdbc-driver-0.2.5.jar` |
| ES 9.x | `softclient4es9-jdbc-driver-0.2.5.jar` |
| ES 6.x | `softclient4es6-jdbc-driver-0.3.0.jar` |
| ES 7.x | `softclient4es7-jdbc-driver-0.3.0.jar` |
| ES 8.x | `softclient4es8-jdbc-driver-0.3.0.jar` |
| ES 9.x | `softclient4es9-jdbc-driver-0.3.0.jar` |

> **Java 11+ recommended** (17+ for ES 9.x): **cross-index JOINs require Java 11+** — the embedded JOIN engine is built on Apache Arrow 18.x, which ships Java-11 bytecode.

Expand All @@ -236,20 +236,20 @@ Driver class: app.softnetwork.elastic.jdbc.ElasticDriver
<dependency>
<groupId>app.softnetwork.elastic</groupId>
<artifactId>softclient4es8-jdbc-driver</artifactId>
<version>0.2.5</version>
<version>0.3.0</version>
</dependency>
```

**Gradle:**

```groovy
implementation 'app.softnetwork.elastic:softclient4es8-jdbc-driver:0.2.5'
implementation 'app.softnetwork.elastic:softclient4es8-jdbc-driver:0.3.0'
```

**sbt:**

```scala
libraryDependencies += "app.softnetwork.elastic" % "softclient4es8-jdbc-driver" % "0.2.5"
libraryDependencies += "app.softnetwork.elastic" % "softclient4es8-jdbc-driver" % "0.3.0"
```

The JDBC driver JARs are Scala-version-independent (no `_2.12` or `_2.13` suffix) and include all required dependencies.
Expand Down Expand Up @@ -337,13 +337,13 @@ For programmatic access, add SoftClient4ES to your project.
resolvers += "Softnetwork" at "https://softnetwork.jfrog.io/artifactory/releases/"

// Choose your Elasticsearch version
libraryDependencies += "app.softnetwork.elastic" %% "softclient4es8-java-client" % "0.20.4"
libraryDependencies += "app.softnetwork.elastic" %% "softclient4es8-java-client" % "0.21.0"
// Add the community extensions for materialized views (optional)
libraryDependencies += "app.softnetwork.elastic" %% "softclient4es-community-extensions" % "0.2.4"
libraryDependencies += "app.softnetwork.elastic" %% "softclient4es-community-extensions" % "0.3.0"
// Add the arrow extensions for cross-index JOIN (required for JOINs; Java 11+)
libraryDependencies += "app.softnetwork.elastic" %% "softclient4es-arrow-extensions" % "0.2.5"
libraryDependencies += "app.softnetwork.elastic" %% "softclient4es-arrow-extensions" % "0.3.0"
// Add the JDBC driver if you want to use it from Scala (optional)
libraryDependencies += "app.softnetwork.elastic" %% "softclient4es-jdbc-driver" % "0.2.5"
libraryDependencies += "app.softnetwork.elastic" %% "softclient4es-jdbc-driver" % "0.3.0"
```

```scala
Expand Down
14 changes: 7 additions & 7 deletions documentation/client/adbc_driver.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,10 @@ Download the self-contained fat JAR for your Elasticsearch version:

| Elasticsearch | Artifact |
|----------------|-----------------------------------------------------|
| ES 6.x | `softclient4es6-adbc-driver-0.2.5.jar` |
| ES 7.x | `softclient4es7-adbc-driver-0.2.5.jar` |
| ES 8.x | `softclient4es8-adbc-driver-0.2.5.jar` |
| ES 9.x | `softclient4es9-adbc-driver-0.2.5.jar` |
| ES 6.x | `softclient4es6-adbc-driver-0.3.0.jar` |
| ES 7.x | `softclient4es7-adbc-driver-0.3.0.jar` |
| ES 8.x | `softclient4es8-adbc-driver-0.3.0.jar` |
| ES 9.x | `softclient4es9-adbc-driver-0.3.0.jar` |

### Maven / Gradle / sbt

Expand All @@ -36,20 +36,20 @@ Download the self-contained fat JAR for your Elasticsearch version:
<dependency>
<groupId>app.softnetwork.elastic</groupId>
<artifactId>softclient4es8-adbc-driver</artifactId>
<version>0.2.5</version>
<version>0.3.0</version>
</dependency>
```

**Gradle:**

```groovy
implementation 'app.softnetwork.elastic:softclient4es8-adbc-driver:0.2.5'
implementation 'app.softnetwork.elastic:softclient4es8-adbc-driver:0.3.0'
```

**sbt:**

```scala
libraryDependencies += "app.softnetwork.elastic" % "softclient4es8-adbc-driver" % "0.2.5"
libraryDependencies += "app.softnetwork.elastic" % "softclient4es8-adbc-driver" % "0.3.0"
```

---
Expand Down
10 changes: 5 additions & 5 deletions documentation/client/arrow_flight_sql.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,15 +49,15 @@ Available images per ES version:
### Fat JAR

```bash
java -jar softclient4es8-arrow-flight-sql-0.2.5.jar
java -jar softclient4es8-arrow-flight-sql-0.3.0.jar
```

| Elasticsearch | Artifact |
|---------------|----------|
| ES 6.x | `softclient4es6-arrow-flight-sql-0.2.5.jar` |
| ES 7.x | `softclient4es7-arrow-flight-sql-0.2.5.jar` |
| ES 8.x | `softclient4es8-arrow-flight-sql-0.2.5.jar` |
| ES 9.x | `softclient4es9-arrow-flight-sql-0.2.5.jar` |
| ES 6.x | `softclient4es6-arrow-flight-sql-0.3.0.jar` |
| ES 7.x | `softclient4es7-arrow-flight-sql-0.3.0.jar` |
| ES 8.x | `softclient4es8-arrow-flight-sql-0.3.0.jar` |
| ES 9.x | `softclient4es9-arrow-flight-sql-0.3.0.jar` |

---

Expand Down
2 changes: 1 addition & 1 deletion documentation/client/download_analytics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ beacon to a public endpoint with exactly these fields:
|---------------|----------|-----------------------------------------------|
| `source` | `portal` | Where the count came from (the docs button) |
| `driver` | `jdbc` | Which driver family (`jdbc` or `adbc`) |
| `version` | `0.2.5` | The published artifact version |
| `version` | `0.3.0` | The published artifact version |
| `count_delta` | `1` | One download |

A timestamp is added on the server. That is the **entire** record.
Expand Down
14 changes: 7 additions & 7 deletions documentation/client/jdbc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,10 @@ Download the self-contained fat JAR for your Elasticsearch version. The JARs are

| Elasticsearch | Artifact |
|---------------|----------|
| ES 6.x | `softclient4es6-jdbc-driver-0.2.5.jar` |
| ES 7.x | `softclient4es7-jdbc-driver-0.2.5.jar` |
| ES 8.x | `softclient4es8-jdbc-driver-0.2.5.jar` |
| ES 9.x | `softclient4es9-jdbc-driver-0.2.5.jar` |
| ES 6.x | `softclient4es6-jdbc-driver-0.3.0.jar` |
| ES 7.x | `softclient4es7-jdbc-driver-0.3.0.jar` |
| ES 8.x | `softclient4es8-jdbc-driver-0.3.0.jar` |
| ES 9.x | `softclient4es9-jdbc-driver-0.3.0.jar` |

### Build Tool Integration

Expand All @@ -33,20 +33,20 @@ Download the self-contained fat JAR for your Elasticsearch version. The JARs are
<dependency>
<groupId>app.softnetwork.elastic</groupId>
<artifactId>softclient4es8-jdbc-driver</artifactId>
<version>0.2.5</version>
<version>0.3.0</version>
</dependency>
```

**Gradle:**

```groovy
implementation 'app.softnetwork.elastic:softclient4es8-jdbc-driver:0.2.5'
implementation 'app.softnetwork.elastic:softclient4es8-jdbc-driver:0.3.0'
```

**sbt:**

```scala
libraryDependencies += "app.softnetwork.elastic" % "softclient4es8-jdbc-driver" % "0.2.5"
libraryDependencies += "app.softnetwork.elastic" % "softclient4es8-jdbc-driver" % "0.3.0"
```

---
Expand Down
54 changes: 41 additions & 13 deletions documentation/client/repl.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,20 +54,33 @@ It provides:
**On Windows you do not have to install Java yourself.** Since `0.20.4`,
`install.ps1` (and therefore `install.cmd`) resolves Java in this order:

1. `%JAVA_HOME%\bin\java.exe` — when `JAVA_HOME` is set, that is the JVM tested,
1. `<install>\jdk\bin\java.exe` — a JDK a previous run bootstrapped into the
same install directory. It is reused as it stands, so re-running the
installer (to upgrade, to add `-NoExtensions`, to retry a failed download)
never downloads the ~180 MB Temurin zip a second time.
2. `%JAVA_HOME%\bin\java.exe` — when `JAVA_HOME` is set, that is the JVM tested,
not whatever `java` happens to be first on `PATH`; the two frequently differ.
2. the `java` on `PATH`, when `JAVA_HOME` is not set.
3. Neither is present, or the one found is **below the floor** for your ES
3. the `java` on `PATH`, when `JAVA_HOME` is not set.
4. None of those is present, or the one found is **below the floor** for your ES
version ⇒ the installer downloads a portable **Temurin 17** JDK (a zip from
Adoptium, never an MSI, so it needs **no administrator rights**) and unpacks
it to `<install>\jdk`.
it to `<install>\jdk`. The new JDK is unpacked and checked before any
existing one is removed, so a failed download never leaves you without a JVM.

Java 17 satisfies both floors, so there is only ever one JDK to think about. The
bootstrapped JDK lives **inside the install directory**: `uninstall.ps1` removes
it along with everything else, and nothing machine-wide is modified — the
installer sets `JAVA_HOME` and `PATH` **for its own session only**. Later
sessions do not need them, because the generated launcher applies the same order
and finds `<install>\jdk` by relative path.
and finds `<install>\jdk` by relative path — and refuses to start, naming the
version it found, if that JVM turns out to be below the floor (a stale
`JAVA_HOME` is the usual cause) rather than letting the JVM fail with
`UnsupportedClassVersionError`.

If an install fails part way through — a version that does not exist, an
unreachable repository — a bootstrapped JDK is left in place on purpose and the
installer says where it is: the next attempt reuses it. Delete the install
directory if you are not going to retry.

On Linux and macOS `install.sh` still expects a suitable Java to be present.

Expand Down Expand Up @@ -126,16 +139,30 @@ install.cmd
```

A local `install.ps1` always wins, so a downloaded pair stays self-consistent —
put both files in the same directory when you want a pinned copy rather than
whatever is on `main`.
put both files in the same directory when you want a specific `install.ps1`.

What the fallback fetches is **pinned to a release tag, not to `main`**, and is
checked against a SHA-256 recorded in `install.cmd` before it is run; a mismatch
is a hard failure, and the download goes to a fresh temporary directory that is
removed when the run ends. So `install.cmd` on its own installs with the
installer of the release it belongs to, never with whatever is currently on
`main`. To use `main`'s installer instead:

```bat
set SOFTCLIENT4ES_INSTALL_REF=main
install.cmd
```

That drops the integrity check — the pinned hash belongs to the pinned tag —
and `install.cmd` says so unless you also set `SOFTCLIENT4ES_INSTALL_SHA256`.

`install.cmd` accepts exactly the flags `install.ps1` does and forwards them
verbatim, so every option, default and fallback documented below applies
unchanged — there is no second implementation to drift:

```bat
install.cmd -ListVersions -EsVersion 8
install.cmd -Target "C:\tools\softclient4es" -EsVersion 8 -Version 0.20.4
install.cmd -Target "C:\tools\softclient4es" -EsVersion 8 -Version 0.21.0
install.cmd -EsVersion 9 -NoExtensions
install.cmd -Help
```
Expand Down Expand Up @@ -188,8 +215,9 @@ install.cmd -ListVersions -EsVersion 8
• 0.20.2
• 0.20.3
• 0.20.4
• 0.21.0

Total: 4 version(s)
Total: 5 version(s)

To install a specific version:
./install.sh --es-version 8 --version <version>
Expand Down Expand Up @@ -217,7 +245,7 @@ install.cmd -ListVersions -EsVersion 8
./install.sh --list-versions --es-version 8

# Install specific version
./install.sh --es-version 8 --version 0.20.4
./install.sh --es-version 8 --version 0.21.0

# Install for Elasticsearch 9 (requires Java 17+)
./install.sh --es-version 9
Expand All @@ -226,7 +254,7 @@ install.cmd -ListVersions -EsVersion 8
./install.sh --target /opt/softclient4es

# Full custom installation
./install.sh --target ~/tools/softclient4es --es-version 7 --version 0.20.4
./install.sh --target ~/tools/softclient4es --es-version 7 --version 0.21.0
```

#### Windows
Expand All @@ -239,7 +267,7 @@ install.cmd -ListVersions -EsVersion 8
.\install.ps1 -ListVersions -EsVersion 8

# Install specific version
.\install.ps1 -EsVersion 8 -Version 0.20.4
.\install.ps1 -EsVersion 8 -Version 0.21.0

# Install for Elasticsearch 9 (requires Java 17+)
.\install.ps1 -EsVersion 9
Expand All @@ -248,7 +276,7 @@ install.cmd -ListVersions -EsVersion 8
.\install.ps1 -Target "C:\tools\softclient4es"

# Full custom installation
.\install.ps1 -Target "C:\tools\softclient4es" -EsVersion 7 -Version 0.20.4
.\install.ps1 -Target "C:\tools\softclient4es" -EsVersion 7 -Version 0.21.0
```

---
Expand Down
12 changes: 8 additions & 4 deletions documentation/sql/ddl_statements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,8 +58,8 @@ A SQL table corresponds to:

| SQL Definition | Elasticsearch Structure |
|-----------------------------------------|----------------------------------------------------|
| `CREATE TABLE` without `PARTITIONED BY` | **Concrete index** |
| `CREATE TABLE` with `PARTITIONED BY` | **Index template** (legacy ES6 or composable ES7+) |
| `CREATE TABLE` without `PARTITION BY` | **Concrete index** |
| `CREATE TABLE` with `PARTITION BY` | **Index template** (legacy ES6 or composable ES7+) |

### Index-backed table (no partitioning)

Expand All @@ -79,13 +79,17 @@ Creates:

### Template-backed table (with partitioning)

The clause is `PARTITION BY <column> (<granularity>)` — the column first, the granularity in
parentheses after it. The parentheses are required when a granularity is given; omit the
granularity entirely and it defaults to `DAY`.

```sql
CREATE TABLE users (
id INT,
birthdate DATE,
PRIMARY KEY (id)
)
PARTITIONED BY (birthdate MONTH);
PARTITION BY birthdate (MONTH);
```

Creates:
Expand Down Expand Up @@ -304,7 +308,7 @@ CREATE TABLE users (
birthdate DATE,
PRIMARY KEY (id)
)
PARTITIONED BY (birthdate MONTH);
PARTITION BY birthdate (MONTH);
```

### Table Options (index settings)
Expand Down
Loading
Loading