======================

Crate Data Java Client

======================

.. highlight:: java

The client module exposes a very simple interface to query Crate using

SQL.

Installation

============

Maven

-----

The easiest way to use the crate client is to include it as a dependency using

maven::

<dependency>

<groupId>io.crate<groupId>

<artifactId>crate-client</artifactId>

<version>0.38.0</version>

</dependency>

From source

-----------

See :ref:`Development <client_develop>` for further details.

Usage

=====

A minimal example is just a few lines of code::

import io.crate.client.CrateClient;

CrateClient client = new CrateClient("server1.crate.org:4300", "server2.crate.org:4300");

SQLResponse r = client.sql("select firstName, lastName from users").actionGet();

System.out.println(Arrays.toString(r.cols()));

// outputs ["firstName", "lastName"]

for (Object[] row: r.rows()){

System.out.println(Arrays.toString(row));

}

// outputs the users. For example:

// ["Arthur", "Dent"]

// ["Ford", "Perfect"]

The `CrateClient` takes multiple servers as arguments. They are used in a

round-robin fashion to distribute the load. In case a server is unavailable it

will be skipped.

By default, the column data types are not serialized. In order to get

these, one must defined it at the `SQLRequest` object::

import io.crate.client.CrateClient;

CrateClient client = new CrateClient("server1.crate.org:4300", "server2.crate.org:4300");

SQLRequest request = new SQLRequest("select firstName, lastName from users");

request.includeTypesOnResponse(true);

SQLResponse r = client.sql().actionGet();

// Get the data type of the first column

DataType dataType = r.columnTypes()[0]

System.out.print(dataType.getName())

// outputs: "string"

.. note::

Queries are executed asynchronous. `client.sql("")` will return a

`Future<SQLResponse>` and code execution is only blocked if

`.actionGet()` is called on it.