Phoenix is a SQL skin over HBase, delivered as a client-embedded JDBC driver, powering the HBase use cases at Salesforce.com. Phoenix targets low-latency queries (milliseconds), as opposed to batch operation via map/reduce. To see what's supported, go to our language reference guide, read more on our wiki, and download it here.
Become the standard means of accessing HBase data through a well-defined, industry standard API.
Tired of reading already and just want to get started? Listen to the Phoenix talks from Hadoop Summit 2013 and HBaseConn 2013, check out our FAQs, and jump over to our quick start guide here or map to your existing HBase tables as described here and start querying now.
The Phoenix query engine transforms your SQL query into one or more HBase scans, and orchestrates their execution to produce standard JDBC result sets. Direct use of the HBase API, along with coprocessors and custom filters, results in performance on the order of milliseconds for small queries, or seconds for tens of millions of rows.
Tables are created and altered through DDL statements, and their schema is stored and versioned on the server in an HBase table. Columns are defined as either being part of a multi-part row key, or as key/value cells. You can also map Phoenix on to existing tables (see the wiki for more details).
Applications interact with Phoenix through a standard JDBC interface; all the usual interfaces are supported, including Connection, Statement, PreparedStatement, and ResultSet. The driver class is com.salesforce.phoenix.jdbc.PhoenixDriver, JDK 1.5+ automatically registers JDBC driver on classpath, and the connection url is jdbc:phoenix: followed by the zookeeper quorum hostname specification plus optionally the port number and/or root node. For example:
Connection conn = DriverManager.getConnection("jdbc:phoenix:localhost");
For detailed documentation on the current level of SQL support, see our language reference guide. For details about how Phoenix handles schema, transactions, and more, see the wiki.
- HBase v0.94.4+ (0.96 is not yet supported)
- JDK 6 or higher
- All the system requirements
- Maven 3.X (https://maven.apache.org/)
To install a pre-built phoenix, use these directions:
- Download and expand the latest phoenix-[version]-install.tar from download page
- Remove prior phoenix-[version].jar from every HBase region server.
- Add the phoenix-[version].jar to the classpath of every HBase region server. An easy way to do this is to copy it into the HBase lib directory.
- Restart all region servers.
- Remove prior phoenix-[version]-client.jar from the classpath of any Phoenix client.
- Add the phoenix-[version]-client.jar to the classpath of any Phoenix client.
Alternatively, you can build it yourself using maven by following these build instructions.
Wanted to get started quickly? Take a look at our FAQs and take our quick start guide here.
A terminal interface to execute SQL from the command line is now bundled with Phoenix v 1.2. To start it, execute the following from the bin directory:
$ sqlline.sh localhost
To execute SQL scripts from the command line, you can include a SQL file argument like this:
$ sqlline.sh localhost ../examples/stock_symbol.sql
For more information, see the manual.
In addition, you can use the bin/psql.sh to load CSV data or execute SQL scripts. For example:
$ psql.sh localhost ../examples/web_stat.sql ../examples/web_stat.csv ../examples/web_stat_queries.sql
Other alternatives include:
- Using our map-reduce based CSV loader for bigger data sets
- Mapping an existing HBase table to a Phoenix table and using the UPSERT SELECT command to populate a new table.
- Populating the table through our UPSERT VALUES command.
If you'd rather use a client GUI to interact with Phoenix, download and install SQuirrel. Since Phoenix is a JDBC driver, integration with tools such as this are seamless. Here are the setup steps necessary:
- Remove prior phoenix-[version]-client.jar from the lib directory of SQuirrel
- Copy the phoenix-[version]-client.jar into the lib directory of SQuirrel (Note that on a Mac, this is the internal lib directory).
- Start SQuirrel and add new driver to SQuirrel (Drivers -> New Driver)
- In Add Driver dialog box, set Name to Phoenix
- Enter com.salesforce.phoenix.jdbc.PhoenixDriver in the Class Name textbox. Press OK to close this dialog.
- Switch to Alias tab and create the new Alias (Aliases -> New Aliases)
- In the dialog box, Name: any name, Driver: Phoenix, User Name: anything, Password: anything
- Construct URL as follows: jdbc:phoenix: zookeeper quorum server. For example, to connect to a local HBase use: jdbc:phoenix:localhost
- Press Test (which should succeed if everything is setup correctly) and press OK to close.
- Now double click on your newly created Phoenix alias and click Connect.
- Navigate to File --> New Session Properties --> Tab SQL and uncheck the "Remove multi line comment (/.../) from SQL before sending it to database" so that hints you include in queries are not stripped.
- Now you are ready to run SQL queries against Phoenix.
Through SQuirrel, you can issue SQL statements in the SQL tab (create tables, insert data, run queries), and inspect table metadata in the Object tab (i.e. list tables, their columns, primary keys, and types).
Currently, Phoenix hosts its own maven repository in github. This is done for convience and will later be moved to a 'real' maven repository. You can add it to your mavenized project by adding the following to your pom:
<repositories>
...
<repository>
<id>phoenix-github</id>
<name>Phoenix Github Maven</name>
<url>https://raw.github.com/forcedotcom/phoenix/maven-artifacts/releases</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
<releases>
<enabled>true</enabled>
</releases>
</repository>
...
</repositories>
<dependencies>
...
<dependency>
<groupId>com.salesforce</groupId>
<artifactId>phoenix</artifactId>
<version>2.2.1</version>
</dependency>
...
</dependencies>
The best place to see samples are in our unit tests under src/test/java. The ones in the endToEnd package are tests demonstrating how to use all aspects of the Phoenix JDBC driver. We also have some examples in the examples directory.
##Mailing List## Join one or both of our Google groups:
- Phoenix HBase User for users of Phoenix.
- Phoenix HBase Dev for developers of Phoenix.
and follow the Phoenix blog here.