HBase SQL (Phoenix) FAQ-ApsaraDB for HBase(Hbase)-阿里云帮助中心

What JAR packages for the latest version of ali-phoenix are released in the Maven Central Repository?

The deployment packages for ali-phoenix 4.x are as follows:

GroupId	ArtifactId	Latest version
com.aliyun.phoenix	ali-phoenix	4.12.0-AliHBase-1.1-0.9
com.aliyun.phoenix	ali-phoenix-hive	4.12.0-AliHBase-1.1-0.9
com.aliyun.phoenix	ali-phoenix-spark	4.12.0-AliHBase-1.1-0.9
com.aliyun.phoenix	ali-phoenix-pherf	4.12.0-AliHBase-1.1-0.9
com.aliyun.phoenix	ali-phoenix-queryserver	4.12.0-AliHBase-1.1-0.9
com.aliyun.phoenix	ali-phoenix-queryserver-client	4.12.0-AliHBase-1.1-0.9
com.aliyun.phoenix	ali-phoenix-pig	4.12.0-AliHBase-1.1-0.9
com.aliyun.phoenix	ali-phoenix-flume	4.12.0-AliHBase-1.1-0.9
com.aliyun.phoenix	ali-phoenix-core	4.12.0-AliHBase-1.1-0.9

The deployment packages for ali-phoenix 5.x are as follows:

GroupId	ArtifactId	Latest version
com.aliyun.phoenix	ali-phoenix-shaded-thin-client	5.2.5-HBase-2.x

Note

To avoid package conflicts between the thin client and third-party business applications, use the thin client shade package.

What is the ali-phoenix JDBC URL format?

Use the fat client when QueryServer is disabled, and the thin client when QueryServer is enabled. Note that ali-phoenix does not support keytab-based authentication, so the Java Database Connectivity (JDBC) URL format differs from Apache Phoenix.

Fat client driver

URL syntax

  jdbc:phoenix:[[ZK_HOST1:port, ZK_HOST2:port, ZK_HOST3:port | comma-separated ZooKeeper Quorum [:port] [:hbase root znode] ]

Simple URL examples

jdbc:phoenix:localhost   
jdbc:phoenix:localhost:123:/hbase  
jdbc:phoenix:v1,v2,v3:123:/hbase  
jdbc:phoenix:v1:2181,v2:2181,v3:2181:/hbase  
jdbc:phoenix:v1:2181,v2:2181,v3:2181

Thin client driver

URL syntax

jdbc:phoenix:thin:[key=value[;key=value...]]

Simple URL examples

jdbc:phoenix:thin:url=http://localhost:8765;serialization=PROTOBUF

Is QueryServer supported?

HBase 1.x uses Phoenix 4.x in fat client mode. To use QueryServer, you must set it up yourself.
HBase 2.0 includes the HBase SQL service with QueryServer enabled by default.

Is Tracing Web Application supported?

Not currently. This feature is under development for ali-phoenix on ApsaraDB for HBase.

What do I do if building a synchronous secondary index times out?

Phoenix 4.x on HBase 1.0: Add the following timeout configuration to the client, then restart the client.

<property>    
     <name>hbase.rpc.timeout</name>    
     <value>60000000</value>
</property>
<property>    
     <name>hbase.client.scanner.timeout.period</name>    
     <value>60000000</value>
</property>
<property>    
        <name>phoenix.query.timeoutMs</name>   
        <value>60000000</value>
</property>

Phoenix 5.x on HBase 2.0: Modify these parameters in the console parameter settings, then restart the HBase SQL service. You do not need to restart HBase — only the HBase SQL service (Phoenix).

Note

In a Phoenix 5.x cluster, adjusting timeout parameters affects online queries. Build the index using a fat client or a MapReduce cluster instead. For more information, see

Index building

.

How do I enable Namespace Mapping?

Steps to enable for 4.x

Add the following configuration to the client.

<property>    
     <name>hbase.rpc.timeout</name>    
     <value>60000000</value>
</property>
<property>    
     <name>hbase.client.scanner.timeout.period</name>    
     <value>60000000</value>
</property>
<property>    
        <name>phoenix.query.timeoutMs</name>   
        <value>60000000</value>
</property>

Contact ApsaraDB for HBase support to enable the server-side parameters.
Restart the HBase cluster.

Steps to enable for 5.x
1. Log in to the console.
2. Configure parameters.
  
  Set phoenix.schema.isNamespaceMappingEnabled and phoenix.schema.mapSystemTablesToNamespace to true.
3. Restart the HBase cluster.
4. Restart the SQL service.
Note
You must configure two identical sets of parameters with different descriptions. One set is for the query server, and the other is for the HBase server. You must configure both sets.

Are connection pools supported?

Phoenix 4.x version 4.12.0.X supports connection pools via PhoenixConnectionPool.java.

Phoenix 5.x is based on a thin client implementation, so PhoenixConnectionPool.java does not apply. Use a third-party connection pool such as MyBatis instead. See this reference for an example.

Can I disconnect the client if index creation takes too long?

No. Index creation has two steps: the server synchronizes data from the source table to the index table, then the client sends a request to set the index table status to active. The first step runs on the server after the client initiates the request, but the second step requires an active client connection.

How fast is data synchronized when creating a synchronous index table?

Indexing 10 million records typically takes 5 to 20 minutes. The actual time depends on cluster configuration and resource usage.

What should I do if the client disconnects because index creation takes too long?

After a disconnect, the index table is usually left in the building state. Check the status with the !table command in sqlline — the index is complete only when the status changes to active. To recover, choose one of these options:

Rebuild the index using the alter index command.
Delete the index table in the building state, increase the client timeout, and create the index again.

How do I import data from a relational database into a Phoenix table in ApsaraDB for HBase?

Use DataX. For examples, see Examples.

What should I do if I encounter the error `ERROR 599(42912): Default enable Force index, please set phoenix.force.index=false to disable it....,` during a query?

Phoenix enforces index usage during SQL compilation to prevent full table scans. This error occurs when a query filters on a non-primary-key, non-index column. To allow such queries, disable forced index checking:

Phoenix 4.x: Set phoenix.force.index to false in the client's hbase-site.xml, then restart the client.
Phoenix 5.x: Set phoenix.force.index to false in the console parameter settings, then restart the HBase SQL service.

What should I do if I get a `java.sql.SQLException: java.lang.IllegalArgumentException: Connection is null or closed` error when using a Druid connection pool with Spring Boot?

Phoenix caches connections internally. Wrapping it with an external connection pool like Druid causes conflicts — some connections get closed unexpectedly. Remove the external pool and rely on Phoenix's built-in connection cache.

Why do I get a `phoenixdb.errors.InternalError: ('', None, None, None)` error when I use a Python client to connect to QueryServer and try to read or write data after a period of inactivity?

The open-source Python client does not automatically reconnect after a timeout. When a connection through a Server Load Balancer (SLB) instance goes idle and times out, the next request is routed to a different QueryServer node, which causes this error.

To fix this, replace the open-source client with the Alibaba Cloud phoenix-python client, which handles reconnection automatically:

Download the Alibaba Cloud phoenix-python client. Click to download.
If you have an existing phoenix-python driver installed, remove it first.
```
rm -rf /usr/lib/python${version}/site-packages/phoenixdb*
```
Decompress the downloaded package, navigate to the phoenixdb directory, and install the driver.
```
python setup.py install
```

Does Phoenix support multi-tenancy?

The grant and revoke commands are not currently supported.