The Phoenix Query Server provides an alternative means for interaction with Phoenix and HBase. Soon this will enable access from environments other than the JVM.


Phoenix 4.4 introduces a stand-alone server that exposes Phoenix to “thin” clients. It is based on the Avatica component of Apache Calcite. The query server is comprised of a Java server that manages Phoenix Connections on the clients’ behalf. The client implementation is currently a JDBC driver with minimal dependencies. Two transport mechanisms are current supported: JSON and Protocol Buffers (available as of Phoenix 4.7 as the default). There’s also a sqlline script that uses the thin client.

Avatica is still relatively early in its life-cycle. With the introduction of the Protobuf transport, Avatica is moving towards backwards compatibility with the provided thin JDBC driver. There are no such backwards compatibility guarantees for the JSON API.

To repeat, there is no guarantee of backwards compatibility with the JSON transport; however, compatibility with the Protobuf transport is stabilizing (although, not tested thoroughly enough to be stated as “guaranteed”).


The query server and its JDBC client are part of the standard Phoenix distribution. They require no additional dependencies.



The server component is managed through bin/ Its usage is as follows

bin/ [start|stop]

When invoked with no arguments, the query server is launched in the foreground, with logging directed to the console.

The first argument is an optional start or stop command to the daemon. When either of these are provided, it will take appropriate action on a daemon process, if it exists.

Any subsequent arguments are passed to the main class for interpretation.

The server is packaged in a standalone jar, phoenix-server-<version>-runnable.jar. This jar and HBASE_CONF_DIR on the classpath are all that is required to launch the server.


Phoenix provides two mechanisms for interacting with the query server. A JDBC driver is provided in the standalone phoenix-<version>-thin-client.jar. The script bin/ is available for the command line.

The JDBC connection string is composed as follows:


<scheme> specifies the transport protocol used when communicating with the server. The only supported transport at this time is http.

<server-hostname> is the name of the host offering the service.

<port> is the port number on which the host is listening. Default is 8765, though this is configurable (see below).

A full list of options that can be provided via the JDBC URL string is available in the below table

The script bin/ is intended to behave identically to its sibling script bin/ It supports the following usage options.

bin/ [[scheme://]host[:port]] [sql_file]

The first optional argument is a connection URL, as described previously. When not provided, scheme defaults to http, host to localhost, and port to 8765.

bin/ http://localhost:8765

The second optional parameter is a sql file from which to read commands.

Wire API documentation

The API itself is documented in the Apache Calcite project as it is the Avatica API – there is no wire API defined in Phoenix itself.


Protocol Buffer API

For more information in building clients in other languages that work with Avatica, please feel free to reach out to the Apache Calcite dev mailing list.


Server components are spread across a number of java packages, so effective logging configuration requires updating multiple packages. The default server logging configuration sets the following log levels:

As of the time of this writing, the underlying Avatica component respects the following configuration options. They are exposed via hbase-site.xml configuration.

Configurations relating to the server instantiation.
Property Description Default
phoenix.queryserver.http.port Specifies a port the server will listen on. Default is 8765. 8765
phoenix.queryserver.metafactory.class The Avatica Meta.Factory class to instantiate. org.apache.phoenix.queryserver.server.PhoenixMetaFactoryImpl
phoenix.queryserver.serialization The transport/serialization format, either PROTOBUF or JSON. PROTOBUF
Configurations relating to server connecting to a secure cluster.
Property Description Default When set to "kerberos", the server will attempt to log in before initiating Phoenix connections. Specified hbase-default.xml
phoenix.queryserver.keytab.file The key to look for keytab file. unset
phoenix.queryserver.kerberos.principal The kerberos principal to use when authenticating. unset
phoenix.queryserver.dns.nameserver The DNS hostname default
phoenix.queryserver.dns.interface The name of the network interface to query for DNS. default
Configurations relating to the server connection cache.
Property Description Default
avatica.connectioncache.concurrency Connection cache concurrency level. Default is 10. 10
avatica.connectioncache.initialcapacity Connection cache initial capacity. Default is 100. 100
avatica.connectioncache.maxcapacity Connection cache maximum capacity. Approaching this point, the cache will start to evict least recently used connection objects. Default is 1000. 1000
avatica.connectioncache.expiryduration Connection cache expiration duration. Any connections older than this value will be discarded. Default is 10 minutes. 10
avatica.connectioncache.expiryunit Connection cache expiration unit. Unit modifier applied to the value provided in avatica.connectioncache.expiryunit. Default is minutes. MINUTES
JDBC URL options.
url The URL of the QueryServer. null
serialization The client-side analogy to phoenix.queryserver.serialization in the server to control how the client should serialize data to send to the QueryServer. PROTOBUF
timeZone The time zone the JDBC connection should use. If not provided, the time zone will be specified by JVM. The value of this should be parseable by Java's TimeZone class. null
Configurations relating to the server statement cache.
Property Description Default
avatica.statementcache.concurrency Statement cache concurrency level. Default is 100. 100
avatica.statementcache.initialcapacity Statement cache initial capacity. Default is 1000. 1000
avatica.statementcache.maxcapacity Statement cache maximum capacity. Approaching this point, the cache will start to evict least recently used statement objects. Default is 10000. 10000
avatica.statementcache.expiryduration Statement cache expiration duration. Any statements older than this value will be discarded. Default is 5 minutes. 5
avatica.statementcache.expiryunit Statement cache expiration unit. Unit modifier applied to the value provided in avatica.statementcache.expiryunit. Default is minutes. MINUTES

Back to top