0
# Apache Phoenix Core
1

2
Apache Phoenix Core is a SQL engine for Apache HBase that provides JDBC connectivity and SQL query capabilities over HBase. It enables users to interact with HBase using standard SQL syntax while leveraging HBase's scalability and performance characteristics.
3

4
## Package Information
5

6
**Package Name:** `org.apache.phoenix:phoenix-core`
7
**Package Type:** Maven Library
8
**Language:** Java
9
**Version:** 5.2.1
10

11
### Maven Installation
12

13
```xml
14
<dependency>
15
    <groupId>org.apache.phoenix</groupId>
16
    <artifactId>phoenix-core</artifactId>
17
    <version>5.2.1</version>
18
</dependency>
19
```
20

21
## Core Imports
22

23
The main entry points for Phoenix Core require these essential imports:
24

25
```java
26
// Primary JDBC driver
27
import org.apache.phoenix.jdbc.PhoenixDriver;
28
import org.apache.phoenix.jdbc.PhoenixConnection;
29

30
// Query services
31
import org.apache.phoenix.query.ConnectionQueryServices;
32
import org.apache.phoenix.query.QueryServices;
33

34
// Schema management
35
import org.apache.phoenix.schema.PTable;
36
import org.apache.phoenix.schema.PMetaData;
37

38
// Data types
39
import org.apache.phoenix.schema.types.PDataType;
40

41
// Standard JDBC imports
42
import java.sql.*;
43
```
44

45
## Basic Usage
46

47
### Establishing a Connection
48

49
```java
50
import org.apache.phoenix.jdbc.PhoenixDriver;
51
import java.sql.*;
52

53
// Register the Phoenix driver
54
Class.forName("org.apache.phoenix.jdbc.PhoenixDriver");
55

56
// Connect to HBase via Phoenix
57
String url = "jdbc:phoenix:localhost:2181";
58
Connection connection = DriverManager.getConnection(url);
59

60
// Create a statement
61
Statement stmt = connection.createStatement();
62

63
// Execute queries
64
ResultSet rs = stmt.executeQuery("SELECT * FROM my_table");
65
while (rs.next()) {
66
    String name = rs.getString("name");
67
    int value = rs.getInt("value");
68
    // Process results
69
}
70
```
71

72
### Creating Tables
73

74
```java{ .api }
75
Statement stmt = connection.createStatement();
76

77
// Create a Phoenix table (maps to HBase table)
78
stmt.executeUpdate(
79
    "CREATE TABLE users (" +
80
    "  id BIGINT NOT NULL, " +
81
    "  name VARCHAR, " +
82
    "  email VARCHAR, " +
83
    "  created_date DATE " +
84
    "  CONSTRAINT pk PRIMARY KEY (id))"
85
);
86
```
87

88
## Architecture
89

90
Phoenix Core provides a comprehensive SQL-on-HBase solution with several key architectural components:
91

92
### SQL-on-HBase Layer
93
Phoenix translates SQL queries into native HBase operations, providing:
94
- **Query Optimization**: Cost-based query optimization and execution planning
95
- **Predicate Pushdown**: Filtering operations pushed to HBase region servers
96
- **Secondary Indexes**: Global and local secondary index support
97
- **Statistics**: Table and column statistics for query optimization
98

99
### JDBC Compliance
100
Full JDBC 4.0 compliance including:
101
- **Standard Interfaces**: Driver, Connection, Statement, PreparedStatement, ResultSet
102
- **Metadata Support**: Complete database and result set metadata
103
- **Transaction Support**: ACID transactions with Phoenix transaction manager
104

105
### Distributed Architecture
106
- **Client-Server**: Thin client with server-side processing via HBase coprocessors
107
- **High Availability**: Connection failover and load balancing
108
- **Parallel Processing**: Multi-threaded query execution and parallel scans
109

110
## Capabilities
111

112
Phoenix Core provides extensive functionality across multiple domains:
113

114
### JDBC API
115
Complete JDBC implementation with Phoenix-specific extensions for HBase integration.
116

117
**Key Components:**
118
```java{ .api }
119
// Driver registration and connection management
120
PhoenixDriver driver = new PhoenixDriver();
121
PhoenixConnection connection = driver.connect(url, properties);
122

123
// Statement execution with monitoring
124
PhoenixPreparedStatement stmt = connection.prepareStatement(sql);
125
PhoenixResultSet results = stmt.executeQuery();
126
```
127

128
**Learn more:** [JDBC API Documentation →](jdbc.md)
129

130
### Query Compilation and Services
131
Advanced query compilation framework that transforms SQL into optimized execution plans.
132

133
**Key Components:**
134
```java{ .api }
135
// Query services for metadata and execution
136
ConnectionQueryServices queryServices = connection.getQueryServices();
137

138
// Query compilation and planning
139
QueryCompiler compiler = new QueryCompiler();
140
QueryPlan plan = compiler.compile(statement, context);
141
```
142

143
**Learn more:** [Query Compilation Documentation →](query-compilation.md)
144

145
### Schema and Metadata Management
146
Comprehensive schema management with strong typing and metadata caching.
147

148
**Key Components:**
149
```java{ .api }
150
// Table and column metadata
151
PTable table = connection.getTable(tableName);
152
PColumn column = table.getColumn(columnName);
153

154
// Metadata cache management
155
PMetaData metaData = connection.getMetaData();
156
PTableRef tableRef = metaData.getTableRef(tableName);
157
```
158

159
**Learn more:** [Schema and Metadata Documentation →](schema-metadata.md)
160

161
### Data Type System
162
Rich type system with Phoenix-specific types and array support.
163

164
**Key Components:**
165
```java{ .api }
166
// Core data types
167
PDataType varchar = PVarchar.INSTANCE;
168
PDataType integer = PInteger.INSTANCE;
169
PDataType decimal = PDecimal.INSTANCE;
170

171
// Array types
172
PDataType varcharArray = PVarcharArray.INSTANCE;
173
PDataType integerArray = PIntegerArray.INSTANCE;
174
```
175

176
**Learn more:** [Data Types Documentation →](types.md)
177

178
### Exception Handling
179
Comprehensive exception hierarchy with detailed error codes and messages.
180

181
**Key Components:**
182
```java{ .api }
183
// Exception construction
184
SQLExceptionInfo.Builder builder = new SQLExceptionInfo.Builder(code);
185
SQLException exception = builder.setMessage(message).build().buildException();
186

187
// Schema-specific exceptions
188
throw new TableNotFoundException(tableName);
189
throw new ColumnNotFoundException(columnName);
190
```
191

192
**Learn more:** [Exception Handling Documentation →](exceptions.md)
193

194
### Expression Framework
195
Powerful expression system supporting functions, operators, and custom expressions.
196

197
**Key Components:**
198
```java{ .api }
199
// Expression evaluation
200
Expression expression = LiteralExpression.newConstant(value);
201
ImmutableBytesWritable result = new ImmutableBytesWritable();
202
boolean success = expression.evaluate(tuple, result);
203

204
// Function expressions
205
FunctionExpression function = new SomeScalarFunction(arguments);
206
```
207

208
**Learn more:** [Expression Framework Documentation →](expressions.md)
209

210
### Query Execution
211
Optimized query execution with parallel processing and result iteration.
212

213
**Key Components:**
214
```java{ .api }
215
// Execution planning and iteration
216
ResultIterator iterator = queryPlan.iterator();
217
Tuple tuple = iterator.next();
218

219
// Mutation state management
220
MutationState mutationState = connection.getMutationState();
221
mutationState.commit();
222
```
223

224
**Learn more:** [Query Execution Documentation →](execution.md)
225

226
### Configuration and Utilities
227
Extensive configuration options and utility classes for Phoenix operations.
228

229
**Key Components:**
230
```java{ .api }
231
// Configuration properties
232
ConnectionProperty property = ConnectionProperty.QUERY_TIMEOUT;
233
String value = connection.getClientInfo(property.toString());
234

235
// Utility operations
236
byte[] bytes = ByteUtil.concat(array1, array2);
237
String formatted = SchemaUtil.getTableName(schemaName, tableName);
238
```
239

240
**Learn more:** [Configuration and Utilities Documentation →](configuration.md)
241

242
### Server-Side Components
243
HBase coprocessors and server-side processing for distributed operations.
244

245
**Key Components:**
246
```java{ .api }
247
// Coprocessor interfaces
248
PhoenixCoprocessor coprocessor = new MetaDataEndpointImpl();
249

250
// Index building and management
251
IndexBuilder indexBuilder = new PhoenixIndexBuilder();
252
IndexWriter indexWriter = new ParallelWriterIndexCommitter();
253
```
254

255
**Learn more:** [Server-Side Components Documentation →](server.md)
256

257
### MapReduce Integration
258
Native MapReduce support for bulk operations and data processing.
259

260
**Key Components:**
261
```java{ .api }
262
// MapReduce input/output formats
263
PhoenixInputFormat inputFormat = new PhoenixInputFormat();
264
PhoenixOutputFormat outputFormat = new PhoenixOutputFormat();
265

266
// Bulk loading tools
267
BulkLoadTool bulkLoader = new BulkLoadTool();
268
```
269

270
**Learn more:** [MapReduce Integration Documentation →](mapreduce.md)
271

272
### Monitoring and Metrics
273
Comprehensive monitoring framework with detailed metrics collection.
274

275
**Key Components:**
276
```java{ .api }
277
// Metrics collection
278
MetricType metricType = MetricType.QUERY_TIME;
279
GlobalClientMetrics.GLOBAL_QUERY_TIME.increment(duration);
280

281
// Table-specific metrics
282
TableMetricsManager metricsManager = TableMetricsManager.getInstance();
283
```
284

285
**Learn more:** [Monitoring and Metrics Documentation →](monitoring.md)
286

287
### Transaction Support
288
ACID transaction support with Phoenix transaction management.
289

290
**Key Components:**
291
```java{ .api }
292
// Transaction client interfaces
293
PhoenixTransactionClient txClient = TransactionFactory.getTransactionClient();
294

295
// Transaction context management
296
TransactionContext txContext = txClient.newTransactionContext();
297
```
298

299
**Learn more:** [Transaction Support Documentation →](transactions.md)
300

301
## Documentation Navigation
302

303
This documentation is organized into focused sections covering different aspects of Phoenix Core:
304

305
- **[JDBC API](jdbc.md)** - Complete JDBC implementation and Phoenix extensions
306
- **[Query Compilation](query-compilation.md)** - Query services and compilation framework
307
- **[Schema & Metadata](schema-metadata.md)** - Table, column, and metadata management
308
- **[Data Types](types.md)** - Phoenix type system and implementations
309
- **[Exception Handling](exceptions.md)** - Exception hierarchy and error management
310
- **[Expression Framework](expressions.md)** - Expression evaluation and functions
311
- **[Query Execution](execution.md)** - Execution planning and result iteration
312
- **[Configuration](configuration.md)** - Configuration options and utilities
313
- **[Server Components](server.md)** - Coprocessors and server-side processing
314
- **[MapReduce](mapreduce.md)** - MapReduce integration and bulk operations
315
- **[Monitoring](monitoring.md)** - Metrics collection and monitoring
316
- **[Transactions](transactions.md)** - Transaction management and ACID support
317

318
Each section provides comprehensive API documentation with practical examples and usage patterns.