IoT Benchmark
---
![](https://img.shields.io/badge/platform-MacOS%20%7C%20Linux%20%7C%20Windows-yellow.svg)
![](https://img.shields.io/badge/java--language-1.8-blue.svg)

You can also read [中文版本](README-cn.md).

- [1. Overview](#1-overview)
- [2. Supported database types](#2-supported-database-types)
- [3. Quick Start](#3-quick-start)
  - [3.1. Prerequisites](#31-prerequisites)
  - [3.2. How to get it](#32-how-to-get-it)
  - [3.3. Quick Start](#33-quick-start)
- [4. Related articles](#4-related-articles)

# 1. Overview

![IoT Benchmark Architecture](https://github.com/apache/iotdb/assets/46039728/1fbf027d-0955-4de6-b727-57dbeaf2a5ab)

IoT-Benchmark is a benchmarking tool used to evaluate the performance of time series databases and real-time databases in the Industrial Internet of Things (IIoT) scenario. It has the following features:
1. **Cross-platform support**: Supports mainstream operating systems, and can start tests and obtain results through simple commands.
2. **Integrates multiple test functions in one, able to meet diverse test needs**:
   1. Generates periodic time series data according to the configuration and directly inserts and queries.
   2. Writes the generated data to the corresponding location on the disk.
   3. Loads data from the generated data set generated on the disk, writes and queries.
   4. Performs correctness verification tests on data and query results respectively.
3. **Supports multiple types of databases**: Supports mainstream time series databases and real-time database products on the market such as InfluxDB and IoTDB.
4. **Diversified test report generation**: Supports storing basic test information and results in various forms such as files and MySQL for further query or analysis.
5. **Test result visualization**: Integrates with Tableau to visualize test results.

# 2. Supported database types

Currently supports the following databases, versions and connection methods:

|       Database       |  Version   |
| :------------------: | :--------: |
|        IoTDB         |    v1.x    |
|       InfluxDB       | v1.x, v2.x |
|       QuestDB        |   v6.0.7   |
| Microsoft SQL Server |  2016 SP2  |
|   VictoriaMetrics    |  v1.64.0   |
|        SQLite        |     --     |
|       OpenTSDB       |   2.4.1    |
|       KairosDB       |     --     |
|     TimescaleDB      |     --     |
|     TimescaleDB      |  Cluster   |
|       TDengine       |  2.2.0.2   |
|       TDengine       |   3.0.1    |
|      PI Archive      |    2016    |

# 3. Quick Start

## 3.1. Prerequisites

To use IoT Benchmark, you need:

1. Java 8
2. Maven: It is not recommended to use the mirror source. You can use the Alibaba Cloud mirror source in China.
3. The appropriate version of the database

Tips:

- The CSV recording mode can only be used in Linux systems to record relevant system information during the test.

- We recommend using MacOs or Linux systems. This article takes MacOS and Linux systems as examples. If you use Windows systems, please use the `benchmark.bat` script in the `conf` folder to start the benchmark.

## 3.2. How to get it

After ensuring that the above conditions are met, clone the source code from git:

```
git clone https://github.com/apache/iotdb.git
```

The default main branch is the master branch. If you want to use other branches, please enter the project root directory after cloning and use the following command to view all available branches:

```
git branch -a
```

After finding the branch name you want to work on, use the following command to switch to it:

```
git checkout [branch name]
```

Use the following command to complete the construction of iot-benchmark through Maven:

```
mvn clean package -Dmaven.test.skip=true
```
This command will compile the core module of iot-benchmark and all other related databases.hmark through Maven:

```
mvn clean package -Dmaven.test.skip=true
```
This command will compile the core module of iot-benchmark and all other related databases.

## 3.3. Quick Start

Tip: All test results in this document are from the following environment:

```
CPU: I7-11700
Memory: 32G DDR4
System disk: 512G SSD (INTEL SSDPEKNU512GZ)
Data disk: 2T HDD (WDC WD40EZAZ-00SF3B0)
```

After the compilation is completed, taking IoTDB v1.0 as an example, **you need to first start the corresponding version of IoTDB service on port 6667 of the local machine**. (If you still have questions about using IoTDB, please refer to the instructions in [IoTDB_README.md](https://github.com/apache/iotdb/blob/master/README_ZH.md)). After successfully starting the IoTDB service, you can go to the `iot-benchmark/iotdb-1.0/target/iot-benchmark-iotdb-1.0/iot-benchmark-iotdb-1.0` folder and use `./benchmark.sh` to start the test of IoTDB v1.0. We recommend using the matching version for testing to achieve the best results.

[Test configuration file](https://github.com/supersshhhh/iot-benchmark/blob/patch-1/Testconfigurations.md)

```

cd iotdb-1.0/target/iot-benchmark-iotdb-1.0/iot-benchmark-iotdb-1.0
./benchmark.sh
```

This will perform a write test using the default configuration. After the test starts, if the execution is correct, you will see the scrolling test execution information, some of which are as follows:

```
...
2022-05-08 14:26:36,478 INFO cn.edu.tsinghua.iot.benchmark.client.DataClient:137 - pool-2-thread-4 17.10% workload is done.
2022-05-08 14:26:41,479 INFO cn.edu.tsinghua.iot.benchmark.client.DataClient:137 - pool-2-thread-13 56.59% workload is done.
2022-05-08 14:26:41,479 INFO cn.edu.tsinghua.iot.benchmark.client.DataClient:137 - pool-2-thread-2 18.01% workload is done.
2022-05-08 14:26:41,480 INFO cn.edu.tsinghua.iot.benchmark.client.DataClient:137 - pool-2-thread-14 54.01% workload is done.
...
```

When the test is finished, the statistics of this test will be displayed as follows:

```
...
2022-05-08 14:40:54,243 INFO  cn.edu.tsinghua.iot.benchmark.mode.BaseMode:154 - All dataClients finished.
----------------------Main Configurations----------------------
########### Test Mode ###########
BENCHMARK_WORK_MODE=testWithDefaultPath
########### Database Connection Information ###########
DOUBLE_WRITE=false
DBConfig=
  DB_SWITCH=IoTDB-100-SESSION_BY_TABLET
  HOST=[127.0.0.1]
########### Data Mode ###########
GROUP_NUMBER=10
DEVICE_NUMBER=50
REAL_INSERT_RATE=1.0
SENSOR_NUMBER=500
IS_SENSOR_TS_ALIGNMENT=true
IS_OUT_OF_ORDER=false
OUT_OF_ORDER_RATIO=0.5
########### Data Amount ###########
OPERATION_PROPORTION=1:0:0:0:0:0:0:0:0:0:0
CLIENT_NUMBER=20
LOOP=10000
BATCH_SIZE_PER_WRITE=100
START_TIME=2022-01-01T00:00:00+08:00
POINT_STEP=200
OP_MIN_INTERVAL=0
INSERT_DATATYPE_PROPORTION=1:1:1:1:1:1
ENCODINGS=PLAIN/PLAIN/PLAIN/PLAIN/PLAIN/PLAIN
COMPRESSOR=SNAPPY
########### Other Param ###########
IS_DELETE_DATA=true
CREATE_SCHEMA=true
BENCHMARK_CLUSTER=false

---------------------------------------------------------------
main measurements:
Create schema cost 0.30 second
Test elapsed time (not include schema creation): 1238.79 second
----------------------------------------------------------Result Matrix----------------------------------------------------------
Operation                okOperation              okPoint                  failOperation            failPoint                throughput(point/s)
INGESTION                500000                   25000000000              0                        0                        20180954.09
PRECISE_POINT            0                        0                        0                        0                        0.00
TIME_RANGE               0                        0                        0                        0                        0.00
VALUE_RANGE              0                        0                        0                        0                        0.00
AGG_RANGE                0                        0                        0                        0                        0.00
AGG_VALUE                0                        0                        0                        0                        0.00
AGG_RANGE_VALUE          0                        0                        0                        0                        0.00
GROUP_BY                 0                        0                        0                        0                        0.00
LATEST_POINT             0                        0                        0                        0                        0.00
RANGE_QUERY_DESC         0                        0                        0                        0                        0.00
VALUE_RANGE_QUERY_DESC   0                        0                        0                        0                        0.00
---------------------------------------------------------------------------------------------------------------------------------
--------------------------------------------------------------------------Latency (ms) Matrix--------------------------------------------------------------------------
Operation                AVG         MIN         P10         P25         MEDIAN      P75         P90         P95         P99         P999        MAX         SLOWEST_THREAD
INGESTION                37.78       1.67        2.02        2.29        2.86        4.14        5.62        7.43        759.69      5799.89     8309.40     1227561.44
PRECISE_POINT            0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00
TIME_RANGE               0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00
VALUE_RANGE              0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00
AGG_RANGE                0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00
AGG_VALUE                0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00
AGG_RANGE_VALUE          0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00
GROUP_BY                 0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00
LATEST_POINT             0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00
RANGE_QUERY_DESC         0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00
VALUE_RANGE_QUERY_DESC   0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00        0.00
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------
```

The output contains the overall information of the test, including:
+ Main configuration information
+ Total test time Test elapsed time
+ Total metadata creation time
+ Result matrix
  + okOperation: The number of Request/SQL for different operations that were successfully executed
  + okPoint: The number of data points that were successfully inserted or the number of data points that successfully returned query results
  + failOperation: The number of Request/SQL for different operations that failed to execute
  + failPoint: The number of data points that failed to insert (this value is always 0 for queries)
  + throughput: equal to ```okPoint / Test elapsed time```
  + Detailed parameter description
+ Millisecond latency statistics for different operations
  + Among them, ```SLOWEST_THREAD``` is the maximum cumulative operation time length in the client thread

All the above information will be recorded in the ```logs``` folder of the running device.

The configuration files are stored in `iot-benchmark/iotdb-1.0/target/iot-benchmark-iotdb-1.0/iot-benchmark-iotdb-1.0conf`. Of course, you can also find the configuration files of other supported databases in similar paths. Edit the file to define the test type and related configuration. **Please note that before each test, you must change the DB_SWITCH parameter in the configuration file to match the database to be tested. The corresponding relationship and possible values are as follows:**

|       Database       | Version  | Corresponding sub-project |                                                  DB_SWITCH                                                   |
| :------------------: | :------: | :-----------------------: | :----------------------------------------------------------------------------------------------------------: |
|  IoTDB(1.0/1.1/1.3)  |   1.x    |         iotdb-1.x         | IoTDB-1x0-JDBC
IoTDB-1x0-SESSION_BY_TABLET
IoTDB-1x0-SESSION_BY_RECORD
IoTDB-1x0-SESSION_BY_RECORDS |
|       InfluxDB       |   1.x    |         influxdb          |                                                   InfluxDB                                                   |
|       InfluxDB       |   2.0    |       influxdb-2.0        |                                                 InfluxDB-2.0                                                 |
|       QuestDB        |  6.0.7   |          questdb          |                                                   QuestDB                                                    |
| Microsoft SQL Server | 2016 SP2 |        mssqlserver        |                                                 MSSQLSERVER                                                  |
|   VictoriaMetrics    |  1.64.0  |      victoriametrics      |                                               VictoriaMetrics                                                |
|     TimescaleDB      |    --    |        timescaledb        |                                                 TimescaleDB                                                  |
|     TimescaleDB      | Cluster  |    timescaledb-cluster    |                                             TimescaleDB-Cluster                                              |
|        SQLite        |    --    |          sqlite           |                                                    SQLite                                                    |
|       OpenTSDB       |    --    |         opentsdb          |                                                   OpenTSDB                                                   |
|       KairosDB       |    --    |         kairosdb          |                                                   KairosDB                                                   |
|       TDengine       | 2.2.0.2  |         TDengine          |                                                   TDengine                                                   |
|       TDengine       |  3.0.1   |         TDengine          |                                                  TDengine-3                                                  |
|      PI Archive      |   2016   |         PIArchive         |                                                  PIArchive                                                   |

* For detailed instructions on using different databases, see [Tested Database Example Instructions](./docs/DifferentTestDatabase-EN.md)

At the same time, you can also change the BENCHMARK_WORK_MODE parameter to adjust the running mode of iot-benchmark. Currently, the following are supported:

|       Mode name        |  BENCHMARK_WORK_MODE  | Mode content                                                                                |
| :--------------------: | :-------------------: | :------------------------------------------------------------------------------------------------------------------------------- |
| Conventional test mode |  testWithDefaultPath  | Supports mixed loads of multiple read and write operations                                                                       |
|   Generate data mode   |   generateDataMode    | Benchmark generates data sets to the FILE_PATH path                                                                              |
| Correctness write mode | verificationWriteMode | Loads data sets from the FILE_PATH path for writing. Currently, IoTDB v1.0 and later versions are supported                      |
| Correctness query mode | verificationQueryMode | Loads data sets from the FILE_PATH path for comparison with the database. Currently, IoTDB v1.0 and later versions are supported |

* For more mode details, refer to [Overview of different test modes](./docs/DifferentTestMode-EN.md), [Sample configuration of different test modes](./docs//DifferentTestModeConfig-EN.md)
* For other variable parameter configurations and annotations, please refer to [config.properties](configuration/conf/config.properties), which will not be expanded here.

# 4. Related articles

* [Benchmark Time Series Database with iot-benchmark for IoT Scenarios](https://arxiv.org/abs/1901.08304)

* [Liu Shuai, Qiao Ying, Luo Xiongfei, Zhao Yijing, Wang Hong’an. Key Techniques of Time Series Databases: A Survey[J]. Journal of Computer Research and Development, 2024, 61(3): 614-638. DOI: 10.7544/issn1000-1239.202330536](https://crad.ict.ac.cn/cn/article/doi/10.7544/issn1000-1239.202330536?viewType=HTML)


[![Apache Sedona](docs/image/sedona_logo.png)](https://sedona.apache.org/)

[![Scala and Java build](https://github.com/apache/sedona/actions/workflows/java.yml/badge.svg)](https://github.com/apache/sedona/actions/workflows/java.yml) [![Python build](https://github.com/apache/sedona/actions/workflows/python.yml/badge.svg)](https://github.com/apache/sedona/actions/workflows/python.yml) [![R build](https://github.com/apache/sedona/actions/workflows/r.yml/badge.svg)](https://github.com/apache/sedona/actions/workflows/r.yml) [![Docker image build](https://github.com/apache/sedona/actions/workflows/docker-build.yml/badge.svg)](https://github.com/apache/sedona/actions/workflows/docker-build.yml) [![Example project build](https://github.com/apache/sedona/actions/workflows/example.yml/badge.svg)](https://github.com/apache/sedona/actions/workflows/example.yml) [![Docs build](https://github.com/apache/sedona/actions/workflows/docs.yml/badge.svg)](https://github.com/apache/sedona/actions/workflows/docs.yml)

| Download statistics        | **Maven**  | **PyPI**                                                                                | Conda-forge                                                                                | **CRAN**                                                                                | **DockerHub**                                                                                |
|----------------------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
| Apache Sedona              | 225k/month | [![PyPI - Downloads](https://img.shields.io/pypi/dm/apache-sedona)](https://pepy.tech/project/apache-sedona) [![Downloads](https://static.pepy.tech/personalized-badge/apache-sedona?period=total&units=international_system&left_color=black&right_color=brightgreen&left_text=total%20downloads)](https://pepy.tech/project/apache-sedona) | [![Anaconda-Server Badge](https://anaconda.org/conda-forge/apache-sedona/badges/downloads.svg)](https://anaconda.org/conda-forge/apache-sedona) | [![](https://cranlogs.r-pkg.org/badges/apache.sedona?color=brightgreen)](https://cran.r-project.org/package=apache.sedona) [![](https://cranlogs.r-pkg.org/badges/grand-total/apache.sedona?color=brightgreen)](https://cran.r-project.org/package=apache.sedona) | [![Docker pulls](https://img.shields.io/docker/pulls/apache/sedona?color=brightgreen)](https://hub.docker.com/r/apache/sedona) |
| Archived GeoSpark releases | 10k/month  | [![PyPI - Downloads](https://img.shields.io/pypi/dm/geospark)](https://pepy.tech/project/geospark)[![Downloads](https://static.pepy.tech/personalized-badge/geospark?period=total&units=international_system&left_color=black&right_color=brightgreen&left_text=total%20downloads)](https://pepy.tech/project/geospark)                      |                                                                                |                                                                                |                                                                                |

* [Join the community](#join-the-community)
* [What is Apache Sedona?](#what-is-apache-sedona)
  * [Features](#features)
* [When to use Sedona?](#when-to-use-sedona)
  * [Use Cases](#use-cases)
  * [Code Example](#code-example)
* [Docker image](#docker-image)
* [Building Sedona](#building-sedona)
* [Documentation](#documentation)
* [Powered by](#powered-by)

## Join the community

Follow Sedona on Twitter for fresh news: [Sedona@Twitter](https://twitter.com/ApacheSedona)

Join the Sedona Discord community: [![](https://dcbadge.vercel.app/api/server/9A3k5dEBsY)](https://share.hsforms.com/1Ndql_ZigTdmLlVQc_d1o4gqga4q)

Join the Sedona monthly community office hour: [Google Calendar](https://calendar.google.com/calendar/event?action=TEMPLATE&tmeid=NjI0cWgwcTZndnI1anAzYnFrNHY5Y2wyaTRfMjAyNDA0MDlUMTUwMDAwWiBjX2VmN2Q1NGY1MzA4YTRiN2YyNWFjMzNkMGY3ZWViNTRhM2E3ZjExNWI2ODlmYWY0ZDgyNDI1ZjNjYjVlZGU5MzVAZw&tmsrc=c_ef7d54f5308a4b7f25ac33d0f7eeb54a3a7f115b689faf4d82425f3cb5ede935%40group.calendar.google.com&scp=ALL), Tuesdays from 8 AM to 9 AM Pacific Time, every 4 weeks

[Sedona JIRA](https://issues.apache.org/jira/projects/SEDONA): Bugs, Pull Requests, and other similar issues

[Sedona Mailing Lists](https://lists.apache.org/list.html?sedona.apache.org): [dev@sedona.apache.org](https://lists.apache.org/list.html?dev@sedona.apache.org): project development, general questions or tutorials.

* Please first subscribe and then post emails. To subscribe, please send an email (leave the subject and content blank) to dev-subscribe@sedona.apache.org

## What is Apache Sedona?

Apache Sedona™ is a spatial computing engine that enables developers to easily process spatial data at any scale within modern cluster computing systems such as Apache Spark and Apache Flink. Sedona developers can express their spatial data processing tasks in Spatial SQL, Spatial Python or Spatial R. Internally, Sedona provides spatial data loading, indexing, partitioning, and query processing/optimization functionality that enable users to efficiently analyze spatial data at any scale.

![](docs/image/sedona-ecosystem.png "Sedona Ecosystem")

### Features

Some of the key features of Apache Sedona include:

* Support for a wide range of geospatial data formats, including GeoJSON, WKT, and ESRI Shapefile.
* Scalable distributed processing of large vector and raster datasets.
* Tools for spatial indexing, spatial querying, and spatial join operations.
* Integration with popular geospatial python tools such as GeoPandas.
* Integration with popular big data tools, such as Spark, Hadoop, Hive, and Flink for data storage and querying.
* A user-friendly API for working with geospatial data in the SQL, Python, Scala and Java languages.
* Flexible deployment options, including standalone, local, and cluster modes.

These are some of the key features of Apache Sedona, but it may offer additional capabilities depending on the specific version and configuration.

Click [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/apache/sedona/HEAD?filepath=docs/usecases) and play the interactive Sedona Python Jupyter Notebook immediately!

## When to use Sedona?

### Use Cases:

Apache Sedona is a widely used framework for working with spatial data, and it has many different use cases and applications. Some of the main use cases for Apache Sedona include:

* Automotive data analytics: Apache Sedona is widely used in geospatial analytics applications, where it is used to perform spatial analysis and data mining on large and complex datasets collected from fleets.
* Urban planning and development: Apache Sedona is commonly used in urban planning and development applications to analyze and visualize spatial data sets related to urban environments, such as land use, transportation networks, and population density.
* Location-based services: Apache Sedona is often used in location-based services, such as mapping and navigation applications, where it is used to process and analyze spatial data to provide location-based information and services to users.
* Environmental modeling and analysis: Apache Sedona is used in many different environmental modeling and analysis applications, where it is used to process and analyze spatial data related to environmental factors, such as air quality, water quality, and weather patterns.
* Disaster response and management: Apache Sedona is used in disaster response and management applications to process and analyze spatial data related to disasters, such as floods, earthquakes, and other natural disasters, in order to support emergency response and recovery efforts.

### Code Example:

This example loads NYC taxi trip records and taxi zone information stored as .CSV files on AWS S3 into Sedona spatial dataframes. It then performs spatial SQL query on the taxi trip datasets to filter out all records except those within the Manhattan area of New York. The example also shows a spatial join operation that matches taxi trip records to zones based on whether the taxi trip lies within the geographical extents of the zone. Finally, the last code snippet integrates the output of Sedona with GeoPandas and plots the spatial distribution of both datasets.

#### Load NYC taxi trips and taxi zones data from CSV Files Stored on AWS S3

```python
taxidf = sedona.read.format('csv').option("header","true").option("delimiter", ",").load("s3a://your-directory/data/nyc-taxi-data.csv")
taxidf = taxidf.selectExpr('ST_Point(CAST(Start_Lon AS Decimal(24,20)), CAST(Start_Lat AS Decimal(24,20))) AS pickup', 'Trip_Pickup_DateTime', 'Payment_Type', 'Fare_Amt')
```

```python
zoneDf = sedona.read.format('csv').option("delimiter", ",").load("s3a://your-directory/data/TIGER2018_ZCTA5.csv")
zoneDf = zoneDf.selectExpr('ST_GeomFromWKT(_c0) as zone', '_c1 as zipcode')
```

#### Spatial SQL query to only return Taxi trips in Manhattan

```python
taxidf_mhtn = taxidf.where('ST_Contains(ST_PolygonFromEnvelope(-74.01,40.73,-73.93,40.79), pickup)')
```

#### Spatial Join between Taxi Dataframe and Zone Dataframe to Find taxis in each zone

```python
taxiVsZone = sedona.sql('SELECT zone, zipcode, pickup, Fare_Amt FROM zoneDf, taxiDf WHERE ST_Contains(zone, pickup)')
```

#### Show a map of the loaded Spatial Dataframes using GeoPandas

```python
zoneGpd = gpd.GeoDataFrame(zoneDf.toPandas(), geometry="zone")
taxiGpd = gpd.GeoDataFrame(taxidf.toPandas(), geometry="pickup")

zone = zoneGpd.plot(color='yellow', edgecolor='black', zorder=1)
zone.set_xlabel('Longitude (degrees)')
zone.set_ylabel('Latitude (degrees)')

zone.set_xlim(-74.1, -73.8)
zone.set_ylim(40.65, 40.9)

taxi = taxiGpd.plot(ax=zone, alpha=0.01, color='red', zorder=3)
```

## Docker image

We provide a Docker image for Apache Sedona with Python JupyterLab and a single-node cluster. The images are available on [DockerHub](https://hub.docker.com/r/apache/sedona)

## Building Sedona

* To install the Python package:

  ```
  pip install apache-sedona
  ```

* To compile the source code, please refer to [Sedona website](https://sedona.apache.org/latest-snapshot/setup/compile/)

* Modules in the source code

| Name             | API                                      | Introduction                                           |
|------------------|------------------------------------------|--------------------------------------------------------|
| common           | Java                                     | Core geometric operation logics, serialization, index  |
| spark            | Spark RDD/DataFrame Scala/Java/SQL       | Distributed geospatial data processing on Apache Spark |
| flink            | Flink DataStream/Table in Scala/Java/SQL | Distributed geospatial data processing on Apache Flink |
| snowflake        | Snowflake SQL                            | Distributed geospatial data processing on Snowflake    |
| spark-shaded     | No source code                           | shaded jar for Sedona Spark                            |
| flink-shaded     | No source code                           | shaded jar for Sedona Flink                            |
| snowflake-tester | Java                                     | tester program for Sedona Snowflake                    |
| python           | Spark RDD/DataFrame Python               | Distributed geospatial data processing on Apache Spark |
| R                | Spark RDD/DataFrame in R                 | R wrapper for Sedona                                   |
| Zeppelin         | Apache Zeppelin                          | Plugin for Apache Zeppelin 0.8.1+                      |

## Documentation

* [Spatial SQL in Sedona](https://sedona.apache.org/latest-snapshot/tutorial/sql/)
* [Integrate with GeoPandas and Shapely](https://sedona.apache.org/latest-snapshot/tutorial/geopandas-shapely/)
* [Working with Spatial R in Sedona](https://sedona.apache.org/latest-snapshot/api/rdocs/)

Please visit [Apache Sedona website](http://sedona.apache.org/) for detailed information

## Powered by


<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements.  See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to you under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License.  You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<div align="center">

# Apache Baremaps (Incubating)

[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat&logo=github&color=2370ff&labelColor=454545)](http://makeapullrequest.com)
![Build Passing](https://github.com/baremaps/baremaps/actions/workflows/build.yml/badge.svg)
[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=apache_baremaps&metric=vulnerabilities)](https://sonarcloud.io/project/overview?id=apache_baremaps)
[![Mailing List](https://img.shields.io/badge/Apache-dev_mailing_list-success.svg?logo=apache)](https://lists.apache.org/list.html?dev@baremaps.apache.org)

</div>

**Apache Baremaps** is a toolkit and a set of infrastructure components for creating, publishing, and operating online maps. It provides a data pipeline enabling developers to build maps with different data sources with live reload capabilities. It provides other services commonly used in online maps, such as location search and IP to location.

## 🔥 Live Demo

[Live Demo](https://baremaps.apache.org/map/)

## 📖 How do I use Apache Baremaps?

You can find the documentation on the project's [website](https://baremaps.apache.org/). The following pages showcase the main uses of Apache Baremaps.

- The [OpenStreetMap](https://baremaps.apache.org/documentation/examples/import-osm-into-postgis) example is a good introduction to Baremaps, it shows how to produce high resolution vector tiles.
- The [NaturalEarth](https://baremaps.apache.org/documentation/examples/import-naturalearth-into-postgis) example shows how to produce low resolution vector tiles.
- The [Contour](https://baremaps.apache.org/documentation/examples/import-contour-into-postgis) example shows how to produce contour lines from a digital elevation model.
- The [IP to location](https://baremaps.apache.org/documentation/examples/ip-to-location) example shows how to create and serve an IP to location service in a simple web application.
- The [Geocoding](https://baremaps.apache.org/documentation/examples/geocoding) example shows how to create and serve a geocoding service in a simple web application.

## 👩💻 How do I contribute?

There are many places where you can contribute to Apache Baremaps such as the code, the documentation, the website or the examples.

The official documentation is located in a separate [repository](https://github.com/apache/incubator-baremaps-site).

If you want to contribute to the code you can refer to the following developer guides available in the documentation.

- [Project structure](https://baremaps.apache.org/documentation/developer-manual/project-structure)
- [How to build with Maven](https://baremaps.apache.org/documentation/developer-manual/how-to-build-with-maven)
- [Set up in IntelliJ IDEA](https://baremaps.apache.org/documentation/developer-manual/setup-in-intellij)
- [Geocoder](https://baremaps.apache.org/documentation/developer-manual/geocoder)
- [IP to location](https://baremaps.apache.org/documentation/developer-manual/ip-to-location)
- [Basemap](https://baremaps.apache.org/documentation/developer-manual/basemap)

You can also contribute in the following ways.

- [Create an issue](https://github.com/apache/incubator-baremaps/issues): Report a bug or feature request
- [Join the mailing list](https://lists.apache.org/list.html?dev@baremaps.apache.org): Initiate or participate in project discussions on the mailing list
- Write a post: Write a post to share your use cases and experiences with Apache Baremaps

Finally, check out [CONTRIBUTING](CONTRIBUTING.md) and [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md).

## 📄 License

This project is licensed under Apache License 2.0 - see the [LICENSE](LICENSE) file for details.


[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/ydb-platform/ydb-java-sdk/blob/master/LICENSE)
[![Maven metadata URL](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Frepo1.maven.org%2Fmaven2%2Ftech%2Fydb%2Fydb-sdk-parent%2Fmaven-metadata.xml)](https://mvnrepository.com/artifact/tech.ydb/ydb-sdk-parent)
[![Build](https://img.shields.io/github/actions/workflow/status/ydb-platform/ydb-java-sdk/build.yaml)](https://github.com/ydb-platform/ydb-java-sdk/actions/workflows/build.yaml)
[![CI](https://img.shields.io/github/actions/workflow/status/ydb-platform/ydb-java-sdk/ci.yaml?label=CI)](https://github.com/ydb-platform/ydb-java-sdk/actions/workflows/ci.yaml)
[![Codecov](https://img.shields.io/codecov/c/github/ydb-platform/ydb-java-sdk)](https://app.codecov.io/gh/ydb-platform/ydb-java-sdk)

The Java SDK for YDB enables Java developers to work with YDB.

* [YDB Documentation][ydb-docs]
* [YDB SDK Documentation][sdk-docs]

## Getting Started

#### Connection setup ####

Before you begin, you need to create a database and setup authorization. Please see the [Prerequisites][prerequisites] section of the connection guide in documentation for information on how to do that.

#### Minimum requirements ####

To use YDB Java SDK you will need **Java 1.8+**.

#### Install the SDK ####

The recommended way to use the YDB Java SDK in your project is to consume it from Maven.
Firstly you can import YDB Java BOM to specify correct versions of SDK modules.

```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>tech.ydb</groupId>
            <artifactId>ydb-sdk-bom</artifactId>
            <version>2.2.5</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

After that you can specify the SDK modules that your project needs in the dependencies:
```xml
<dependencies>
    <!-- Scheme service client -->
    <dependency>
        <groupId>tech.ydb</groupId>
        <artifactId>ydb-sdk-scheme</artifactId>
    </dependency>

    <!-- Table service client -->
    <dependency>
        <groupId>tech.ydb</groupId>
        <artifactId>ydb-sdk-table</artifactId>
    </dependency>

    <!-- Topic service client -->
    <dependency>
        <groupId>tech.ydb</groupId>
        <artifactId>ydb-sdk-topic</artifactId>
    </dependency>

    <!-- Coordination service client -->
    <dependency>
        <groupId>tech.ydb</groupId>
        <artifactId>ydb-sdk-coordination</artifactId>
    </dependency>
</dependencies>
```

## Examples ##

#### Using Maven ####

In [basic example][basic-example] folder there is simple example application that uses YDB Java SDK from Maven.
See the [Connect to a database][connect-to-a-database] section of the documentation for an instruction on how to setup and launch it.

#### Generic examples ####

In [examples][generic-examples] folder you can find more example applications with YDB Java SDK usage.

## How to build
To build the YDB Java SDK artifacts locally, see [Building YDB Java SDK](BUILD.md).

[ydb-docs]: https://ydb.tech/en/docs
[sdk-docs]: https://ydb.tech/en/docs/reference/ydb-sdk/
[prerequisites]: https://ydb.tech/en/docs/concepts/connect
[connect-to-a-database]: https://ydb.tech/en/docs/reference/ydb-sdk/example/java#init
[basic-example]: https://github.com/ydb-platform/ydb-java-examples/tree/master/basic_example
[generic-examples]: https://github.com/ydb-platform/ydb-java-examples


<!--
This file is part of SoSy-Lab Common,
a library of useful utilities:
https://github.com/sosy-lab/java-common-lib

SPDX-FileCopyrightText: 2007-2020 Dirk Beyer <https://www.sosy-lab.org>

SPDX-License-Identifier: Apache-2.0
-->

# SoSy-Lab Common

[![Build Status](https://travis-ci.org/sosy-lab/java-common-lib.svg "Build Status")](https://travis-ci.org/sosy-lab/java-common-lib)
[![Apache 2.0 License](https://img.shields.io/badge/license-Apache--2-brightgreen.svg?style=flat)](https://www.apache.org/licenses/LICENSE-2.0)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.sosy-lab/common/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.sosy-lab/common)

A collection of utilities for Java.

### [Java-Config](https://sosy-lab.github.io/java-common-lib/api/org/sosy_lab/common/configuration/package-summary.html)

  - Library for configuration options injection.

### [Java-Rationals](https://sosy-lab.github.io/java-common-lib/api/org/sosy_lab/common/rationals/package-summary.html)

  - Working with rationals and extended rationals, plus linear expressions.

[Javadoc documentation](https://sosy-lab.github.io/java-common-lib/) for entire project.

## License and Copyright

The license of this project is the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0),
copyright [Dirk Beyer](https://www.sosy-lab.org/people/beyer/) and others.

## Installation

### Using ANT and Ivy

If we use ANT with Ivy in your build process, you can download latest version of
SoSy-Lab Common from our repositories directly.
The updates to the Ivy repository are very frequent, and the latest version can
be easily found.

The dependency is:

```xml
<dependency org="org.sosy_lab" name="common" rev="0.3000" conf="core->runtime; contrib->sources"/>
```

And the Ivy repository URL is:

```xml
https://www.sosy-lab.org/ivy
```

### From Maven Central

The Common library is also published to Maven Central, however the volume of
updates is less frequent.
If you use Maven, the dependency is:

```xml
<dependency>
  <groupId>org.sosy-lab</groupId>
  <artifactId>common</artifactId>
  <version>0.3000</version>
</dependency>
```

Or for Gradle:

```
dependencies {
  compile 'org.sosy-lab:common:0.3000'
}
```

### Manually

The latest JAR can be downloaded directly from the Ivy repository, served at

```
https://www.sosy-lab.org/ivy/org.sosy_lab/common/
```

This option is least recommended, as the required dependencies (namely,
Guava and AutoValue) would need to be downloaded manually.
Download the `.ivy` file corresponding to the obtained `jar` to see
the dependencies and their location in the repository.


# Mine Cells mod by Mim1q

Mine Cells is a mod bringing the world of [Dead Cells](https://dead-cells.com) into Minecraft.
For more info and a feature overview, check out any of the mod pages linked directly below.

## Links

- [CurseForge](https://www.curseforge.com/minecraft/mc-mods/minecells)
- [Modrinth](https://modrinth.com/mod/minecells)

## License

### Code
The source code is licensed under the [MIT](LICENSE) license unless otherwise specified. You may learn from it, copy parts of it for your own project etc. as long as you respect the license's terms.

### Assets
All textures and models - that is, files in the directories listed below and all their subdirectories - are All Rights Reserved.

- `src/main/resources/assets/minecells/textures/`
- `src/main/resources/assets/minecells/models/`
- `datagen/src/main/resources/images/`

You **may not** reuse those in your own projects or redistribute them in any way without my explicit permission.

Because these assets are included in the mod's JAR file, you may not redistribute the mod itself without getting my
permission beforehand. However, feel free to use the mod in modpacks, **as long as they are published through
CurseForge and/or Modrinth and are clearly and completely free to download**.

If you have any questions about these terms or anything else, feel free to contact me:
- on Discord: @Mim1q
- by e-mail: [mim1q.dev@gmail.com](mailto:mim1q.dev@gmail.com)


# MojoHaus Versions Maven Plugin

This is the [versions-maven-plugin](http://www.mojohaus.org/versions-maven-plugin/).

[![Apache License, Version 2.0, January 2004](https://img.shields.io/github/license/mojohaus/versions-maven-plugin.svg?label=License)](http://www.apache.org/licenses/)
[![Maven Central](https://img.shields.io/maven-central/v/org.codehaus.mojo/versions-maven-plugin.svg?label=Maven%20Central)](https://search.maven.org/artifact/org.codehaus.mojo/versions-maven-plugin)
[![Build Status](https://github.com/mojohaus/versions-maven-plugin/workflows/GitHub%20CI/badge.svg?branch=master)](https://github.com/mojohaus/versions-maven-plugin/actions/workflows/maven.yml?query=branch%3Amaster)

## Maintained versions

Versions Maven Plugin requires Maven 3.6.3+ and JDK 1.8+

However, we maintain the latest Plugin version with the latest Maven.

We execute tests against different operating systems and JDKs
by [GitHub Actions](https://github.com/mojohaus/versions-maven-plugin/actions/workflows/maven.yml?query=branch%3Amaster)

## Contributing

### Creating Issues

If you find a problem please first search current opened and closed issues and pull requests.
It can be that someone already has reported similar.

You can also check current [milestone](https://github.com/mojohaus/versions-maven-plugin/milestones)
in order to see what will be in next release.

Only when you can not find similar issue please create a new one in the
[ticket system](https://github.com/mojohaus/versions-maven-plugin/issues)
and describe what is going wrong or what you expect to happen.

If you have a full working example or a log file this is also helpful.

You should of course describe only a single issue in a single ticket and not
mixing up several things into a single issue.

Please always check your issue with the latest Plugin and tha latest Maven version.

### Creating a Pull Request

Before you start working on more complicated change, new feature
it is good practice to create an issue in
the [ticket system](https://github.com/mojohaus/versions-maven-plugin/issues)
or send an emil to [development list](https://www.mojohaus.org/versions-maven-plugin/mailing-lists.html)
and describe what the problem is or what kind of feature you would like to add.
Wait a few days for feedback from other contributors.
Afterwards you can create an appropriate pull request.

It is required if you want to get a pull request to be integrated into please
squash your commits into a single commit which references the optional issue
in the commit message which looks like this:

```
Fixed #Issue - change subject

a description
```

Please take consider that change subject will be used in release notes
and will be present in git history so should be enough descriptive.

This makes it simpler to merge it and this will also close the
appropriate issue automatically in one go.
This make the life as maintainer a little bit easier.

A pull request has to fulfill only a single ticket and should never
create/add/fix several issues in one, cause otherwise the history is hard to
read and to understand and makes the maintenance of the issues and pull request
hard or to be honest impossible.

## Releasing

* Make sure `gpg-agent` is running.
* Execute `./mvnw -B release:prepare release:perform`

For publishing the site do the following:

```
cd target/checkout
../mvnw site
../mvnw scm-publish:publish-scm
```

for multi module site - we need two executions


# Kroxylicious

Kroxylicious, the snappy open source proxy for Apache Kafka

Kroxylicious is a Kafka protocol proxy, addressing use cases such as encryption, multi-tenancy and schema validation.

<!-- TOC -->
* [Kroxylicious](#kroxylicious)
  * [Quick Links](#quick-links)
  * [Build status](#build-status)
  * [License](#license)
  * [Developer Guide](#developer-guide)
  * [Releasing this project](#releasing-this-project)
  * [Performance Testing](#performance-testing)
  * [Kroxylicious Samples](#kroxylicious-samples)
  * [Kubernetes Examples](#kubernetes-examples)
<!-- TOC -->

## Quick Links
- [kroxylicious.io](https://www.kroxylicious.io)
- [Documentation](https://www.kroxylicious.io/kroxylicious)
- [GitHub design and discussion](https://github.com/kroxylicious/design)
- [Community Slack chat](https://kroxylicious.slack.com/)

## Build status
![Maven Central Version](https://img.shields.io/maven-central/v/io.kroxylicious/kroxylicious-parent)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=kroxylicious_kroxylicious&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=kroxylicious_kroxylicious) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=kroxylicious_kroxylicious&metric=coverage)](https://sonarcloud.io/summary/new_code?id=kroxylicious_kroxylicious)

## License

This code base is available under the [Apache License, version 2](LICENSE).

## Developer Guide

See the [Developer Guide](DEV_GUIDE.md).

## Releasing this project

See the [Release Guide](RELEASING.md)

## Performance Testing

See the [Performance Guide](PERFORMANCE.md) for information on running basic performance tests for this proxy.

## Kroxylicious Samples

See [kroxylicious-sample](kroxylicious-sample) to learn more about sample filters. Try them out and customise them for a hands-on introduction to custom filters in Kroxylicious.

## Kubernetes Examples

[kubernetes-examples](kubernetes-examples/README.md) illustrate Kroxylicious running inside a Kubernetes
Cluster integrated with components such as Strimzi and cert-manager.


## OpenSearch upgrades, migrations, and comparison tooling

OpenSearch upgrade, migration, and comparison tooling facilitates OpenSearch migrations and upgrades. With these tools, you can set up a proof-of-concept environment locally using Docker containers or deploy to AWS using a one-click deployment script. Once set up and deployed, users can redirect their production traffic from a source cluster to a provisioned target cluster, enabling a comparison of results between the two clusters. All traffic directed to the source cluster is stored for future replay. Meanwhile, traffic to the target cluster is replayed at an identical rate to ensure a direct "apple-to-apple" comparison. This toolset empowers users to fine-tune cluster configurations and manage workloads more effectively.

## Table of Contents

- [ Supported cluster versions and platforms](#supported-cluster-versions-and-platforms)
- [Build and deploy](#build-and-deploy)
    - [Local deployment](#local-deployment)
    - [AWS deployment](#aws-deployment)
- [Developer contributions](#developer-contributions)
    - [Pre-commit hooks](#pre-commit-hooks)
    - [Traffic Capture Proxy and Replayer](#traffic-capture-proxy-and-replayer)
    - [Running Tests](#running-tests)
- [Security](#security)
- [License](#license)

## Supported cluster versions and platforms

There are numerous combinations of source clusters, target clusters, and platforms. While the tools provided in this repository might work with various combinations, they might not support breaking changes between different source and target versions. Below is a list of supported source and target versions and platforms.

### Supported Source and Target Versions
* Elasticsearch 6.x (Coming soon...)
* Elasticsearch 7.0 - 7.17.x
* OpenSearch 1.x
* OpenSearch 2.x

### Supported Source and Target Platforms
* Self-managed (hosted by cloud provider)
* Self-managed (on-premises)
* Managed cloud offerings (e.g., Amazon OpenSearch, Amazon OpenSearch Serverless)

## Build and deploy

### Local deployment

A containerized end-to-end solution can be deployed locally using the
[Docker Solution](TrafficCapture/dockerSolution/README.md).

### AWS deployment

Refer to [AWS Deployment](deployment/README.md) to deploy this solution to AWS.

## Developer contributions

### Pre-commit hooks

Developers must run the "install_githooks.sh" script in order to add any pre-commit hooks.  Developers should run these hooks before opening a pull request to ensure checks pass and prevent potential rejection of the pull request."

### Traffic Capture Proxy and Replayer

The TrafficCapture directory hosts a set of projects designed to facilitate the proxying and capturing of HTTP traffic, which can then be offloaded and replayed to other HTTP(S) server(s).

More documentation on this directory including the projects within it can be found here: [Traffic Capture](TrafficCapture/README.md).

### Fetch Migration

The FetchMigration directory hosts tools that simplify the process of backfilling / moving data from one cluster to another.

Further documentation can be found here: [Fetch Migration README](FetchMigration/README.md).

### Running Tests

Developers can run a test script which will verify the end-to-end Local Docker Solution.

More documentation on this test script can be found here:
[End-to-End Testing](test/README.md)

## Security

See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.

## License

This project is licensed under the Apache-2.0 License.

## Releasing

The release process is standard across repositories in this org and is run by a release manager volunteering from amongst [maintainers](MAINTAINERS.md).

1. Create a tag, e.g. 0.1.0, and push it to this GitHub repository.
2. The [release-drafter.yml](.github/workflows/release-drafter.yml) will be automatically kicked off and a draft release will be created.
3. This draft release triggers the [jenkins release workflow](https://build.ci.opensearch.org/job/opensearch-migrations-release) as a result of which the opensearch-migrations toolset is released and published on artifacts.opensearch.org example as https://artifacts.opensearch.org/migrations/0.1.0/opensearch-migrations-0.1.0.tar.gz.
4. Once the above release workflow is successful, the drafted release on GitHub is published automatically.

## Publishing

This project can be published to a local maven repository with:
```sh
./gradlew publishToMavenLocal
```

And subsequently imported into a separate gradle project with (replacing name with any subProject name)
```groovy
repositories {
    mavenCentral()
    mavenLocal()
}

dependencies {
    implementation group: "org.opensearch.migrations.trafficcapture", name: "captureKafkaOffloader", version: "0.1.0-SNAPSHOT"
    //... other dependencies
}
```

The entire list of published subprojects can be viewed with
```sh
./gradlew listPublishedArtifacts
```

To include a testFixture dependency, define the import like

```groovy
testImplementation testFixtures('org.opensearch.migrations.trafficcapture:trafficReplayer:0.1.0-SNAPSHOT')
```


[![Ubuntu build][ubuntu-build-badge]][gh-actions]
[![codecov][codecov-badge]][codecov]
[![license][license-badge]][license]

# Spine Base

This repository contains common data types and utilities used by the Spine SDK subprojects (e.g.
[core-java][core-java]).

## Adding to a Gradle project

Spine Base is not supposed to be used directly in end user project. But if you need to,
here's how you add it to your Gradle project:

```kotlin
dependencies {
    implementation("io.spine:spine-base:$version")
}
```

## Java Support

Starting version `2.0.0-SNAPSHOT.78`, the modules in this repository are built with Java 11.

Prior versions, including all `1.x` versions were assembled with Java 8.

[gh-actions]: https://github.com/SpineEventEngine/base/actions
[ubuntu-build-badge]: https://github.com/SpineEventEngine/base/actions/workflows/build-on-ubuntu.yml/badge.svg
[codecov]: https://codecov.io/gh/SpineEventEngine/base
[codecov-badge]: https://codecov.io/gh/SpineEventEngine/base/branch/master/graph/badge.svg
[license-badge]: https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat
[license]: http://www.apache.org/licenses/LICENSE-2.0
[core-java]: https://github.com/SpineEventEngine/core-java


= Vert.x Auth

image:https://github.com/eclipse-vertx/vertx-auth/actions/workflows/ci-5.x.yml/badge.svg["Build Status (5.x)",link="https://github.com/eclipse-vertx/vertx-auth/actions/workflows/ci-5.x.yml"]
image:https://github.com/eclipse-vertx/vertx-auth/actions/workflows/ci-4.x.yml/badge.svg["Build Status (4.x)",link="https://github.com/eclipse-vertx/vertx-auth/actions/workflows/ci-4.x.yml"]

This module contains auth implementations for Vert.x and common auth interfaces

Particular implementations are stored in sub modules.

Legacy modules (vertx-auth-mongo, vertx-auth-jdbc, vertx-auth-shiro) are maintained at https://github.com/vert-x3/vertx-auth.


[![Badge License]][License]
[![Badge Gradle]][Actions]
[![Badge Crowdin]][Crowdin]

![Banner]

*A mod that adds many useful extensions to **[ComputerCraft]**

and aims to add features that were available in `1.12.2`

mods like **[PeripheralsPlusOne]**.*

[![Button CurseForge]][CurseForge]
[![Button Discord]][Discord]
[![Button Documentation]][Documentation]

## Contributing
Contributions to the project are always welcome!

Read our [Contribution](CONTRIBUTING.md) Guidelines to get started.

## Translating

All translation is done via **[Crowdin]**, as such we

will close pull requests related to translations.

[![Badge Localized]][Crowdin]

## Credits

[@Srendi]

    ***Author***

[@SirEdvin] , [@Olfi01]

    ***Contributor***

[@FatalMerlin]

    ***Ingame Guide + Minor Bug Fixes***

**[Many Other Contributor][Contributors]**

    ❣

[Documentation]: https://advancedperipherals.madefor.cc/
[Contributors]: https://github.com/Seniorendi/AdvancedPeripherals/graphs/contributors
[CurseForge]: https://www.curseforge.com/minecraft/mc-mods/advanced-peripherals
[Actions]: https://github.com/Seniorendi/AdvancedPeripherals/actions
[Crowdin]: https://crowdin.com/project/advanced-peripherals
[Discord]: https://discord.intelligence-modding.de
[Banner]: https://www.bisecthosting.com/images/CF/Advanced_Peripherals/BH_AP_Header.png 'Advanced Peripherals'

[PeripheralsPlusOne]: https://github.com/rolandoislas/PeripheralsPlusOne
[ComputerCraft]: https://www.curseforge.com/minecraft/mc-mods/computercraft

[@FatalMerlin]: https://github.com/FatalMerlin
[@SirEdvin]: https://github.com/SirEdvin
[@Srendi]: https://github.com/Seniorendi
[@Olfi01]: https://github.com/Olfi01

[License]: LICENSE

[Badge Localized]: https://badges.crowdin.net/advanced-peripherals/localized.svg
[Badge Crowdin]: https://img.shields.io/badge/Localized_On-Crowdin-373d4c?style=for-the-badge&labelColor=464e62&logoColor=white&logo=Crowdin
[Badge License]: https://img.shields.io/badge/License-Apache_2.0-961b1f?style=for-the-badge&labelColor=D22128&logoColor=white&logo=Apache
[Badge Gradle]: https://img.shields.io/github/workflow/status/Seniorendi/AdvancedPeripherals/Gradle%20Snapshot?style=for-the-badge&labelColor=034654&color=023741&logoColor=white&logo=Gradle

[Button Documentation]: https://img.shields.io/badge/Documentation-5abcff?style=for-the-badge&logoColor=white&logo=GitBook
[Button CurseForge]: https://img.shields.io/badge/CurseForge-6441A4?style=for-the-badge&logoColor=white&logo=CurseForge
[Button Discord]: https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logoColor=white&logo=Discord


# TTRPG convert CLI

![GitHub all releases](https://img.shields.io/github/downloads/ebullient/ttrpg-convert-cli/total?color=success)

A Command-Line Interface designed to convert TTRPG data from 5eTools and Pf2eTools into crosslinked, tagged, and formatted markdown optimized for [Obsidian.md](https://obsidian.md).

Jump
⬇ Download
⚙ Configuration
🎨 Examples
🎨 Templates

🚜 Changelog
🗺 Source Map
📖 5eTools
📖 Pf2eTools
📖 Homebrew

I use [Obsidian](https://obsidian.md) to keep track of my campaign notes. This project parses json sources for materials that I own from the 5etools mirror to create linked and formatted markdown that I can reference in my notes.

> [!TIP]
>
> - 🚜 [**Review the changelog**](CHANGELOG.md) for new capabilities (✨) and breaking changes (🔥💥).
> - 🔮 Check out [**Conventions**](#conventions) and  [**Recommendations**](#recommendations-for-using-the-cli)

## Using the Command Line

This tool works in the command line, which is a text-based way to give instructions to your computer.
If you're new to it, we have resources to help you get started below.

If you don't have a favorite method already, or you don't know what those words mean, here are some resources to get you started:

- For MacOS / OSX Users:
    - Start with the built-in `Terminal` application.
    - [Learn the Mac OS X Command Line][]
- For Windows Users:
    - Use the native [Command Prompt][]
    - [Open a command prompt in a folder (Windows)][]
    - [Running executables from the command line (Windows)][]
    - To show emoji in Windows Commmand Prompt: `chcp 65001` and choose a font with emoji support (Consolas is one).

[Learn the Mac OS X Command Line]: https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line
[Command Prompt]: https://www.digitaltrends.com/computing/how-to-use-command-prompt/
[Open a command prompt in a folder (Windows)]: https://www.lifewire.com/open-command-prompt-in-a-folder-5185505
[Running executables from the command line (Windows)]: https://www.techwalla.com/articles/how-to-use-quotcdquot-command-in-command-prompt-window

## Install the TTRPG Convert CLI

There are several (many!) options for running `ttrpg-convert`.
Choose whichever you are the most comfortable with:

- **Using Windows?** See the [Windows README](README-WINDOWS.md)
- `jbang`: [Use JBang!][jbang] (hides Java; sets up command aliases)
- `brew`: [Use Homebrew (MacOS or Linux)][brew] (uses platform binaries)
- `bin`: [Use a pre-built platform binary][bin] (no Java required)
- `jar`: [Use Java to run the jar][jar]
- `src`: [Build from source][src]

| Platform       | Options  |
|----------------|----------|
|  Linux         | [jbang][], [brew][], [bin][], [jar][], [src][] |
|  Mac (Arm)     | [brew][], [jbang][], [bin][], [jar][], [src][] |
|  Mac (Intel)   | [brew][], [jbang][], [bin][], [jar][], [src][] |
|  Windows       | [📝](README-WINDOWS.md), [jbang][], [bin][], [jar][], [src][]  |
|  Windows (Old) | [📝](README-WINDOWS.md), [jbang][], [jar][], [src][]  |
|  Windows (WSL) | [brew][], [jbang][], [jar][], [src][] |

[jbang]: ./docs/alternateRun.md#use-jbang
[brew]: ./docs/alternateRun.md#use-homebrew
[bin]: ./docs/alternateRun.md#use-pre-built-platform-binary
[jar]: ./docs/alternateRun.md#use-java-to-run-the-jar
[src]: ./docs/alternateRun.md#build-and-run-from-source

## Recommendations for using the CLI

- 🔐 Treat generated content as a big ball of mud. Stick it in a corner of your vault *treat it as read-only*.

    Trust us, you will want to regenerate content from time to time. It is cheap and easy to do if you don't have your own edits to worry about.

- 🔎 Have the CLI generate output into a separate directory and use a comparison tool to preview changes.

    You can use `git diff` to compare arbitrary directories, for example:

    ```bash
    git diff --no-index vault/compendium/bestiary generated/compendium/bestiary
    ```

- 📑 Use a copy tool that only updates modified files, like [rsync][], to avoid unnecessary file copying when updating your vault. Use the checksum option (`-c`) to compare file contents; the file modification date is meaningless given generated files are recreated when the tool is run. We have some suggestions in [discussion #220][sync-discussion], but it is very much a work in progress.

[rsync]: https://stackoverflow.com/a/19540611
[sync-discussion]: https://github.com/ebullient/ttrpg-convert-cli/discussions/220

### Required plugins

- **Admonitions** ([git](https://github.com/javalent/admonitions)/[obsidian](obsidian://show-plugin?id=obsidian-admonition)): The admonitions plugin supports a codeblock style that is used for more complicated content like statblocks. See [Admonition plugin notes](docs/README.md#admonitions) for more recommendations.

### Recommended plugins

- **Force note view mode by front matter** ([git](https://github.com/bwydoogh/obsidian-force-view-mode-of-note)/[obsidian](obsidian://show-plugin?id=obsidian-view-mode-by-frontmatter)): I use this plugin to treat these generated notes as essentially read-only. See [Force note view mode plugin settings](docs/README.md#force-note-view-mode-by-front-matter) for recommendations.

- **Fantasy Statblocks** ([git](https://github.com/javalent/fantasy-statblocks)/[obsidian](obsidian://show-plugin?id=obsidian-5e-statblocks)): Templates for rendering monsters can define a `statblock` in the document body or provide a full or abridged yaml monster in the document header to update monsters in the plugin's bestiary.
    - See [Fantasy Statblocks plugin settings](docs/README.md#fantasy-statblocks) for recommendations.
    - See [Templates](examples/templates) for related template customization.

- **Initiative Tracker** ([git](https://github.com/javalent/initiative-tracker)/[obsidian](obsidian://show-plugin?id=initiative-tracker)): Templates for rendering monsters can include information in the header to define monsters that initiative tracker can use when constructing encounters. See [Initiative Tracker plugin settings](docs/README.md#initiative-tracker) for recommendations.

- **Dataview** ([git](https://github.com/blacksmithgu/obsidian-dataview)/[obsidian](obsidian://show-plugin?id=dataview)): This plugin can be used to create custom views of the data, and to create custom queries to find and display data in your vault. See [Working with dataview](docs/README.md#working-with-dataview) for recommendations.

## Conventions

- **Links.** Documents generated by this plugin will use markdown links rather than wiki links. A [css snippet](examples/css-snippets/hide-markdown-link-url.css) can make these links less invasive in edit mode by hiding the URL portion of the string.

- **File names.** To avoid conflicts and issues with different operating systems, all file names are slugified (all lower case, symbols stripped, and spaces replaced by dashes). This is a familiar convention for those used to jekyll, hugo, or other blogging systems.

    - File names for resources outside of the core books (PHB, MM, and DMG) have the abbreviated source name appended to the end to avoid file collisions.
    - All files have an `aliases` attribute that contains the original name of the resource.

- **Organization.** Files are generated in two roots: `compendium` and `rules`. The location of these roots is [configurable](docs/configuration.md#specify-target-paths-paths-key). These directories will be populated depending on the sources you have enabled.

    - `compendium` contains files for items, spells, monsters, etc.
    The `compendium` directory is further organized into subdirectories for each type of content. For example, all items are in the `compendium/items` directory.

    - `rules` contains files for conditions, weapon properties, variant rules, etc.

    - `css-snippets` will contain **CSS files for special fonts** used by some content. You will need to copy these snippets into your vault (`.obsidian/snippets`) and enable them (`Appearance -> Snippets`) to ensure all content in your vault is styled correctly.

- **Styles.** Every document has a `cssclasses` attribute that assigns a CSS class. We have some [CSS snippets](examples/css-snippets/) that you can use to customize elements of the compendium.
    - 5e tools: `json5e-background`, `json5e-class`, `json5e-deck`, `json5e-deity`, `json5e-feat`, `json5e-hazard`, `json5e-item`, `json5e-monster`, `json5e-note`, `json5e-object`, `json5e-psionic`, `json5e-race`, `json5e-reward`, `json5e-spell`, and `json5e-vehicle`.
    - pf2e tools: `pf2e`, `pf2e-ability`, `pf2e-action`, `pf2e-affliction`, `pf2e-archetype`, `pf2e-background`, `pf2e-book`, `pf2e-delity`, `pf2e-feat`, `pf2e-hazard`, `pf2e-index`, `pf2e-item`, `pf2e-note`, `pf2e-ritual`, `pf2e-sleep`, `pf2e-trait`.

- **Admonitions.** Generated content uses code-block-style [Admonitions](docs/README.md#admonitions) in addition to Obsidian callouts. We have [Admonition definitions](examples/admonitions/) that you can import to ensure these admonition/callout types are defined.
    - `ad-statblock`
    - 5e tools: `ad-flowchart`, `ad-gallery`, `ad-embed-action`, `ad-embed-feat`, `ad-embed-monster`, `ad-embed-object`, `ad-embed-race`, `ad-embed-spell`, `ad-embed-table`
    - pf2e tools: `ad-embed-ability`, `ad-embed-action`, `ad-embed-affliction`, `ad-embed-avatar`, `ad-embed-disease`, `ad-embed-feat`, `ad-embed-item`, `ad-pf2-note`, `ad-pf2-ritual`.

## Convert 5eTools JSON data

> [!NOTE]
> Instructions here use backslashes to wrap lines for readability (a common practice for linux-based command shells).
> *If you are using Windows*, you will need to remove the backslashes and put the command on a single line. You may also need to append `.exe` to the command name (though it should work without).

1. Create a shallow clone of the 5eTools mirror repo (which can/should be deleted afterwards):

    ```shell
    git clone --depth 1 https://github.com/5etools-mirror-2/5etools-mirror-2.github.io.git
    ```

2. Invoke the CLI. In this first example, let's generate indexes and markdown for SRD content:

    ```shell
    ttrpg-convert \
      --index \
      -o dm \
      5etools-mirror-2.github.io/data
    ```

    - `--index` generates two index files: `all-index.json` and `src-index.json`.

        > 🚀 TIP:
        > - Use `all-index.json` to see the reference keys for all discovered content. This can confirm that an included source was actually read.
        > - Use `src-index.json` to see the reference keys for content that was included in the generated output. This can confirm that your source selection is working as expected.

    - `-o dm` The target output directory (`dm` in this case). Files will be created in this directory.

    The rest of the command-line specifies input files:

    - `5etools-mirror-2.github.io/data` Path to the 5etools `data` directory (from a clone or release of the repo)

    This should produce a set of markdown files in the `dm` directory that contains only SRD content.

3. Invoke the command again and include additional sources:

    ```shell
    ttrpg-convert \
        --index \
        -o dm \
        -s PHB,DMG,SCAG \
        5etools-mirror-2.github.io/data
    ```

    - `-s PHB,DMG,SCAG` will include reference material from the *Player's Handbook*, the *Dungeon Master's Guide*, and the *Sword Coast Adventurer's Guide*.

        > 🚀 Note: Only include content you own. Find the identifier for your sources in the [Source Map](./docs/sourceMap.md#source-name-mapping-for-5etools).

We now know that the CLI is working!

Specifying sources on the command line with the `-s` option gets messy in a hurry. Configuration beyond this basic example should use a configuration file, specified with the `-c` option, like this:

```shell
ttrpg-convert \
    --index \
    -o dm \
    -c my-config.json \
    5etools-mirror-2.github.io/data
```

Next step:

- Create your own [configuration file](docs/configuration.md).

## Convert Pf2eTools JSON data

🚜 🚧 🚜 🚧 🚜 🚧 🚜 🚧

> [!NOTE]
> Instructions here use backslashes to wrap lines for readability (a common practice for linux-based command shells).
> *If you are using Windows*, you will need to remove the backslashes and put the command on a single line. You may also need to append `.exe` to the command name (though it should work without).

1. Download a release of the Pf2eTools mirror, or create a shallow clone of the repo (which can/should be deleted afterwards):

    ```shell
    git clone --depth 1 https://github.com/Pf2eToolsOrg/Pf2eTools.git
    ```

2. Invoke the CLI. In this first example, let's generate indexes and markdown for default content:

    ```shell
    ttrpg-convert \
      -g pf2e \
      --index \
      -o dm \
      Pf2eTools/data
    ```

    - `-g pf2e` The game system! Pathfinder 2e!
    - `--index` generates two index files: `all-index.json` and `src-index.json`.

      > 🚀 TIP:
      > - Use `all-index.json` to see the reference keys for all discovered content. This can confirm that an included source was actually read.
      > - Use `src-index.json` to see the reference keys for content that was included in the generated output. This can confirm that your source selection is working as expected.

    - `-o dm` The target output directory. Files will be created in this directory.

    The rest of the command-line specifies input files:

    - `Pf2eTools/data` Path to the Pf2eTools `data` directory (from a clone or release of the repo)

3. Invoke the command again and include additional sources:

    ```shell
    ttrpg-convert \
        -g pf2e \
        --index \
        -o dm \
        -s AV1,GMG \
        Pf2eTools/data
    ```

    - `-s AV1,GMG` will include reference material from the *Abomination Vaults #1: Ruins of Gauntlight*, and the *Gamemastery Guide*.

        > 🚀 Note: Only include content you own. Find the identifier for your sources in the [Source Map](./docs/sourceMap.md#source-name-mapping-for-pf2etools).

We now know that the CLI is working!

Specifying sources on the command line with the `-s` option gets messy in a hurry. Configuration beyond this basic example should use a configuration file, specified with the `-c` option, like this:

```shell
ttrpg-convert \
    -g pf2e \
    --index \
    -o dm \
    -c my-config.json \
    Pf2eTools/data
```

Next step:

- Create your own [configuration file](docs/configuration.md).

## Convert Homebrew JSON data

The CLI tool also has the ability to import homebrewed content, though this content must still fit the json standards that are set by in the [5eTools json spec][5etools JSON] or the PF2eTools json spec (coming soon, similar to 5eTools).

Perhaps the simplest thing to do to import homebrew is to use already existing homebrew data from the 5etools homebrew github repo: <https://github.com/TheGiddyLimit/homebrew>.

> [!TIP]
> 🍺 *You only need the particular file you wish to import*.
>
> Homebrew data is different from the 5etools data. Each homebrew file is a complete reference. If you compare it to cooking: the 5etools mirror repo is organized by ingredient (all of the carrots, all of the onions, ... ); homebrew data is organized by prepared meal / complete receipe.

Adding homebrew content is easiest if you use a [configuration file](./docs/configuration.md), we will assume a file named `my-config.json` for the example below, but you can use any name you like.

> [!IMPORTANT]
> 🚀 Respect copyrights and support content creators; use only the sources you own.

For example, if you wanted to use Benjamin Huffman's popular homebrewed [Pugilist class](https://www.dmsguild.com/product/184921/The-Pugilist-Class):

1. Download a copy of the [Pugilist json file](https://github.com/TheGiddyLimit/homebrew/blob/master/class/Benjamin%20Huffman%3B%20Pugilist.json).

    Save this file to a well-known location on your computer. It is probably easiest if it sits next your 5eTools or Pf2eTools directory.

2. Update your [configuration file](docs/configuration.md) to add a `homebrew` section under `full-source`:

    ```json
    {
      "full-source": {
        "homebrew": [
            "path/to/Benjamin Huffman; Pugilist.json"
        ]
      }
    }
    ```

    - `path/to/` is a placeholder for a relative or absolute path to the file[^1]. There are a few ways to figure out the path to a file.
        - You may be able to drag and drop the file into the terminal window.
        - You may have the ability to right-click on the file and select "Copy Path".
        - *Windows users*: When pasting the path into a text editor, use find/replace to replace all `\` with `/`.

3. Run the command like so (for 5e homebrew):

    ``` shell
    ttrpg-convert \
        --index \
        -o hb-compendium \
        -c my-config.json
        5etools-mirror-2.github.io/data
    ```

    - `-o hb-compendium` is the output directory for generated content.
    - `-c my-config.json'` is the name and/or path to your configuration file.

See [configuration](docs/configuration.md) for more details on how to configure the CLI.

The process is similar for other homebrew, including your own, so long as it is broadly compatible with the [5e-tools json spec](https://wiki.tercept.net/en/Homebrew/FromZeroToHero).

## Where to find help

- There is a `#cli-support` thread in the `#tabletop-games` channel of the [Obsidian Discord](https://discord.gg/veuWUTm).
- There is a `TTRPG-convert-help` post in the `obsidian-support` forum of the [Obsidian TTRPG Community Discord](https://discord.gg/Zpmr37Uv).
- There is a TTRPG-convert tutorial (currently aimed at Windows users, but much of it is helpful no matter your OS) at [Obsidian TTRPG Tutorials](https://obsidianttrpgtutorials.com/Obsidian+TTRPG+Tutorials/Plugin+Tutorials/TTRPG-Convert-CLI/TTRPG-Convert-CLI+5e).
- If you open an issue for an error, run with the `--debug` and `--log` options, and attach the log file to the issue.

### Want to help fix it?

- If you're familiar with the command line and are comfortable running the tool, I hope you'll consider running [unreleased snapshots](docs/alternateRun.md#using-unreleased-snapshots) and reporting issues.
- If you want to contribute, I'll take help of all kinds: documentation, examples, sample templates, stylesheets are just as important as Java code. See [CONTRIBUTING](CONTRIBUTING.md).

## Other notes

This project uses Quarkus, the Supersonic Subatomic Java Framework. If you want to learn more about Quarkus, please visit its website: <https://quarkus.io/>.

This project is a derivative of [fc5-convert-cli](https://github.com/ebullient/fc5-convert-cli), which focused on working to and from FightClub5 Compendium XML files. It has also stolen some bits and pieces from [pockets-cli](https://github.com/ebullient/pockets-cli).

[5etools JSON]: https://wiki.tercept.net/en/Homebrew/FromZeroToHero

[^1]: Description of relative vs absolute file paths: <https://stackoverflow.com/a/10288252> . If you use a relative path, it will be resolved relative to the current working directory, as described here: <https://en.wikipedia.org/wiki/Working_directory>.


# ClickHouse Java Libraries

[![GitHub release (latest SemVer including pre-releases)](https://img.shields.io/github/v/release/ClickHouse/clickhouse-java?style=plastic&include_prereleases&label=Latest%20Release)](https://github.com/ClickHouse/clickhouse-java/releases/) [![GitHub release (by tag)](https://img.shields.io/github/downloads/ClickHouse/clickhouse-java/latest/total?style=plastic)](https://github.com/ClickHouse/clickhouse-java/releases/) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ClickHouse_clickhouse-jdbc&metric=coverage)](https://sonarcloud.io/summary/new_code?id=ClickHouse_clickhouse-jdbc) [![Sonatype Nexus (Snapshots)](https://img.shields.io/nexus/s/com.clickhouse/clickhouse-java?style=plastic&label=Nightly%20Build&server=https%3A%2F%2Fs01.oss.sonatype.org)](https://s01.oss.sonatype.org/content/repositories/snapshots/com/clickhouse/) [![GitHub milestone](https://img.shields.io/github/milestones/progress-percent/ClickHouse/clickhouse-java/4?style=social)](https://github.com/ClickHouse/clickhouse-java/milestone/4)

Java libraries for connecting to ClickHouse and processing data in various formats. Java client is async, lightweight, and low-overhead library for ClickHouse; while JDBC and R2DBC drivers are built on top of the Java client with more dependencies and features. Java 8 or higher is required to use the libraries. In addition, please use ClickHouse 20.7+ or any of [active releases](https://github.com/ClickHouse/ClickHouse/pulls?q=is%3Aopen+is%3Apr+label%3Arelease).

![image](https://user-images.githubusercontent.com/4270380/212460181-2b806482-bc1c-492c-bd69-cdeb2c8845b5.png)

## Features

| Category          | Feature                                                                             | Supported          | Remark                                                                                |
| ----------------- | ----------------------------------------------------------------------------------- | ------------------ |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| API               | [JDBC](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/)                | :white_check_mark: |                                                                                |
|                   | [R2DBC](https://r2dbc.io/)                                                          | :white_check_mark: | supported since 0.4.0                                                                                |
| Protocol          | [HTTP](https://clickhouse.com/docs/en/interfaces/http/)                             | :white_check_mark: | recommended, defaults to `java.net.HttpURLConnection` and it can be changed to `java.net.http.HttpClient`(unstable) or `Apache HTTP Client 5`. Note that the latter was added in 0.4.0 to support custom socket options. |
|                   | [gRPC](https://clickhouse.com/docs/en/interfaces/grpc/)                             | :white_check_mark: | :warning: experimental, works with 22.3+, known to has issue with lz4 compression and may cause high memory usage on server. Planed to be removed from version 0.7.0                                                     |
|                   | [TCP/Native](https://clickhouse.com/docs/en/interfaces/tcp/)                        | :x: | `clickhouse-cli-client`(wrapper of ClickHouse native command-line client) was added in 0.3.2-patch10.                                                                                |
|                   | [Local/File](https://clickhouse.com/docs/en/operations/utilities/clickhouse-local/) | :x:                | `clickhouse-cli-client` will be enhanced to support `clickhouse-local`                                                                                |
| Compatibility     | Server < 20.7                                                                       | :x:                | use 0.3.1-patch(or 0.2.6 if you're stuck with JDK 7)                                                                                |
|                   | Server >= 20.7                                                                      | :white_check_mark: | use 0.3.2 or above. All [active releases](https://github.com/ClickHouse/ClickHouse/pulls?q=is%3Aopen+is%3Apr+label%3Arelease) are supported.                                                                             |
| Compression       | [lz4](https://lz4.github.io/lz4/)                                                   | :white_check_mark: | default                                                                                |
|                   | [zstd](https://facebook.github.io/zstd/)                                            | :white_check_mark: | supported since 0.4.0, works with ClickHouse 22.10+                                                                                |
| Data Format       | RowBinary                                                                           | :white_check_mark: | `RowBinaryWithNamesAndTypes` for query and `RowBinary` for insertion                                                                                |
|                   | TabSeparated                                                                        | :white_check_mark: | :warning: does not support as many data types as RowBinary                                                                                |
| Data Type         | AggregateFunction                                                                   | :white_check_mark: | :warning: does not support `SELECT * FROM table ...`                                                                                |
|                   | Array(\*)                                                                           | :white_check_mark: |                                                                                |
|                   | Bool                                                                                | :white_check_mark: |                                                                                |
|                   | Date\*                                                                              | :white_check_mark: |                                                                                |
|                   | DateTime\*                                                                          | :white_check_mark: |                                                                                |
|                   | Decimal\*                                                                           | :white_check_mark: | `SET output_format_decimal_trailing_zeros=1` in 21.9+ for consistency                                                                                |
|                   | Enum\*                                                                              | :white_check_mark: | can be treated as both string and integer                                                                                |
|                   | Geo Types                                                                           | :white_check_mark: | Point, Ring, Polygon, and MultiPolygon                                                                                |
|                   | Int\*, UInt\*                                                                       | :white_check_mark: | UInt64 is mapped to `long`                                                                                |
|                   | IPv\*                                                                               | :white_check_mark: |                                                                                |
|                   | Map(\*)                                                                             | :white_check_mark: |                                                                                |
|                   | Nested(\*)                                                                          | :white_check_mark: | :warning: broken before 0.4.1                                                                                |
|                   | Object('JSON')                                                                      | :white_check_mark: | supported since 0.3.2-patch8                                                                                |
|                   | SimpleAggregateFunction                                                             | :white_check_mark: |                                                                                |
|                   | \*String                                                                            | :white_check_mark: | :warning: requires `use_binary_string=true` for binary string support since v0.4.0                                                                                |
|                   | Tuple(\*)                                                                           | :white_check_mark: |                                                                                |
|                   | UUID                                                                                | :white_check_mark: |                                                                                |
| High Availability | Load Balancing                                                                      | :white_check_mark: | supported since 0.3.2-patch10                                                                                |
|                   | Failover                                                                            | :white_check_mark: | supported since 0.3.2-patch10                                                                                |
| Transaction       | Transaction                                                                         | :white_check_mark: | supported since 0.3.2-patch11, use ClickHouse 22.7+ for native implicit transaction support                                                                                |
|                   | Savepoint                                                                           | :x:                |                                                                                |
|                   | XAConnection                                                                        | :x:                |                                                                                |
| Misc.             | Centralized Configuration                                                           | :white_check_mark: | supported since 0.4.2, limited to JDBC driver and requires custom server setting `custom_jdbc_config` for all connected JDBC clients - [#1290](../../pull/1290)                                                          |
|                   | INFILE & OUTFILE                                                                    | :white_check_mark: | supported since 0.4.2, limited to JDBC driver and requires `localFile` option - [#1291](../../pull/1291)                                                                                |
|                   | Implicit Type Conversion                                                            | :white_check_mark: | String/number to Date/Time/Timestamp and more                                                                                |
|                   | Object mapping                                                                      | :white_check_mark: | supported since 0.4.6, slow and limited to simple data types                                                                                |

## Planed to be removed

| Feature                        | Version | Remark                                           |
|--------------------------------|---------|--------------------------------------------------|
| Clickhouse ClI Client package  | 0.7.0   | Use clickhouse-client directly instead           |
| ClickHouse GRPC Client package | 0.7.0   | Please use the clickhouse http protocol instead  |
## Usage

The library can be downloaded from both [Github Releases](../../releases) and [Maven Central](https://repo1.maven.org/maven2/com/clickhouse/). Development snapshots(aka. nightly build) are available on [Sonatype OSSRH](https://s01.oss.sonatype.org/content/repositories/snapshots/com/clickhouse/).

```xml
<repositories>
    <repository>
        <id>ossrh</id>
        <name>Sonatype OSSRH</name>
        <url>https://s01.oss.sonatype.org/content/repositories/snapshots/</url>
    </repository>
</repositories>
```

### Java Client

See [examples](../../tree/main/examples/client) and the [docs on the ClickHouse website](https://clickhouse.com/docs/en/integrations/language-clients/java/client).

### JDBC Driver

See [examples](../../tree/main/examples/jdbc) and the [docs on the ClickHouse website](https://clickhouse.com/docs/en/integrations/language-clients/java/jdbc).

## Contributing

Check out our [contributing guide](./CONTRIBUTING.md).