0
# Schema and Metadata Management
1

2
Phoenix provides a comprehensive schema management system with strong typing, metadata caching, and full support for tables, columns, indexes, and other database objects. The metadata system enables efficient query compilation and execution planning.
3

4
## Core Imports
5

6
```java
7
import org.apache.phoenix.schema.*;
8
import org.apache.phoenix.schema.types.*;
9
import org.apache.phoenix.exception.*;
10
import java.sql.*;
11
```
12

13
## Table Metadata
14

15
### PTable
16

17
Core interface representing Phoenix table metadata with complete schema information.
18

19
```java{ .api }
20
public interface PTable extends PMetaDataEntity {
21
    // Basic table information
22
    PName getSchemaName()
23
    PName getTableName()
24
    PName getName()  // Full qualified name
25
    PTableType getType()
26
    long getTimeStamp()
27
    long getSequenceNumber()
28

29
    // Column operations
30
    List<PColumn> getColumns()
31
    PColumn getColumnForColumnName(String name) throws ColumnNotFoundException, AmbiguousColumnException
32
    List<PColumn> getPKColumns()
33
    int getBaseColumnCount()
34
    PColumn getColumnForColumnQualifier(byte[] cq)
35

36
    // Index information
37
    List<PTable> getIndexes()
38
    PIndexState getIndexState()
39
    PName getParentName()
40
    PName getParentTableName()
41

42
    // Table properties
43
    boolean isTransactional()
44
    boolean isImmutableRows()
45
    Integer getSaltBuckets()
46
    String getDefaultFamilyName()
47
    boolean isWALDisabled()
48
    boolean isMultiTenant()
49
    boolean hasViewModifiedUpdateCacheFreq()
50
    Integer getBucketNum()
51

52
    // View and inheritance
53
    ViewType getViewType()
54
    String getViewStatement()
55
    List<PName> getPhysicalNames()
56

57
    // Inner enums
58
    enum ViewType { READ_ONLY, UPDATABLE }
59
    enum IndexType { GLOBAL, LOCAL }
60
    enum LinkType { PHYSICAL_TABLE, PARENT_TABLE, EXCLUDED_COLUMN, CHILD_TABLE }
61
}
62
```
63

64
### PTableType
65

66
Enumeration of Phoenix table types with correct values.
67

68
```java{ .api }
69
public enum PTableType {
70
    SYSTEM('s'),        // System tables (metadata tables)
71
    TABLE('t'),         // Regular Phoenix/HBase tables
72
    VIEW('v'),          // Phoenix views
73
    INDEX('i'),         // Phoenix indexes
74
    PROJECTED('p'),     // Projected tables
75
    SUBQUERY('u');      // Subquery tables
76

77
    public String getSerializedValue()
78
    public static PTableType fromSerializedValue(String serializedValue)
79
}
80
```
81

82
### PIndexState
83

84
Enumeration of Phoenix index states with correct values.
85

86
```java{ .api }
87
public enum PIndexState {
88
    BUILDING("b"),         // Index is being built
89
    USABLE("o"),          // Index is usable for queries
90
    UNUSABLE("x"),        // Index is unusable
91
    ACTIVE("a"),          // Index is active and maintained
92
    INACTIVE("i"),        // Index is inactive
93
    DISABLE("d"),         // Index is disabled
94
    REBUILD("r"),         // Index needs rebuild
95
    PENDING_ACTIVE("j"),  // Index is pending activation
96
    PENDING_DISABLE("k"), // Index is pending disable
97
    CREATE_DISABLE("c");  // Index created in disabled state
98

99
    public String getSerializedValue()
100
    public static PIndexState fromSerializedValue(String serializedValue)
101
}
102
```
103

104
**Usage:**
105
```java
106
PhoenixConnection connection = getPhoenixConnection();
107
PTable table = connection.getTable("users");
108

109
// Basic table info
110
PName schemaName = table.getSchemaName();
111
String fullTableName = table.getName().getString();
112
PTableType tableType = table.getType();
113

114
// Column information
115
List<PColumn> allColumns = table.getColumns();
116
try {
117
    PColumn nameColumn = table.getColumnForColumnName("name");
118
    System.out.println("Found column: " + nameColumn.getName().getString());
119
} catch (ColumnNotFoundException e) {
120
    System.out.println("Column not found");
121
} catch (AmbiguousColumnException e) {
122
    System.out.println("Ambiguous column reference");
123
}
124

125
List<PColumn> pkColumns = table.getPKColumns();
126

127
// Index information
128
List<PTable> indexes = table.getIndexes();
129
boolean hasIndexes = !indexes.isEmpty();
130

131
// Check table type
132
if (table.getType() == PTableType.INDEX) {
133
    PName parentName = table.getParentName();
134
    System.out.println("Index on table: " + parentName);
135
}
136

137
// Check index state
138
if (table.getType() == PTableType.INDEX) {
139
    PIndexState state = table.getIndexState();
140
    if (state == PIndexState.ACTIVE) {
141
        System.out.println("Index is active and can be used");
142
    }
143
}
144
```
145

146
## Column Metadata
147

148
### PColumn
149

150
Interface representing Phoenix column metadata with data type and constraint information.
151

152
```java{ .api }
153
public interface PColumn extends PDatum {
154
    // Basic column information
155
    PName getName()
156
    PName getFamilyName()
157
    int getPosition()
158
    Integer getArraySize()
159

160
    // Column properties
161
    SortOrder getSortOrder()
162
    boolean isRowTimestamp()
163
    boolean isDynamic()
164
    byte[] getViewConstant()
165
    long getTimestamp()
166
    boolean isDerived()
167
    boolean isExcluded()
168
    byte[] getColumnQualifierBytes()
169
    String getExpressionStr()
170
}
171
```
172

173
### PColumnFamily
174

175
Interface representing Phoenix column family metadata.
176

177
```java{ .api }
178
public interface PColumnFamily extends PMetaDataEntity {
179
    PName getName()
180
    List<PColumn> getColumns()
181
    PColumn getColumnForColumnName(String name) throws ColumnNotFoundException
182
    int getPosition()
183
}
184
```
185

186
**Usage:**
187
```java
188
// Column information
189
PColumn column = table.getColumnForColumnName("email");
190
PName columnName = column.getName();
191
PDataType dataType = column.getDataType();
192
boolean isNullable = column.isNullable();
193
SortOrder sortOrder = column.getSortOrder();
194

195
// Check if column is in primary key
196
boolean isPK = table.getPKColumns().contains(column);
197

198
// Get column family (for multi-family tables)
199
PName familyName = column.getFamilyName();
200
if (familyName != null) {
201
    System.out.println("Column family: " + familyName.getString());
202
}
203
```
204

205
## Metadata Cache Management
206

207
### PMetaData
208

209
Interface for Phoenix metadata cache with correct method signatures.
210

211
```java{ .api }
212
public interface PMetaData extends MetaDataMutated, Iterable<PTable> {
213
    // Table retrieval
214
    PTable getTableRef(PTableKey key) throws TableNotFoundException
215
    PSchema getSchema(PTableKey key) throws SchemaNotFoundException
216

217
    // Table operations
218
    PMetaData addTable(PTable table, long resolvedTimestamp) throws SQLException
219
    PMetaData removeTable(PName tenantId, String schemaName, String tableName, String parentTableName, long tableTimeStamp) throws SQLException
220
    PMetaData addColumn(PName tenantId, String tableName, List<PColumn> columns, long tableTimeStamp,
221
                       long tableSeqNum, boolean isImmutableRows, boolean isWALDisabled, boolean isMultitenant,
222
                       boolean storeNulls, boolean isTransactional, long updateCacheFrequency, long resolvedTime) throws SQLException
223
    PMetaData removeColumn(PName tenantId, String tableName, List<PColumn> columnsToRemove, long tableTimeStamp,
224
                          long tableSeqNum, long resolvedTime) throws SQLException
225

226
    // Schema operations
227
    PMetaData addSchema(PSchema schema) throws SQLException
228
    PMetaData removeSchema(PSchema schema, long schemaTimeStamp) throws SQLException
229

230
    // Utility methods
231
    int size()
232
    PMetaData clone()
233
    long getAge(PTableRef ref)
234
}
235
```
236

237
### PSchema
238

239
Class representing Phoenix schema information from the parse package.
240

241
```java{ .api }
242
public class PSchema implements PMetaDataEntity {
243
    public String getSchemaName()
244
    public long getTimeStamp()
245
    public long getEstimatedSize()
246
}
247
```
248

249
### PMetaDataEntity
250

251
Base interface for all metadata entities.
252

253
```java{ .api }
254
public interface PMetaDataEntity {
255
    long getEstimatedSize()
256
}
257
```
258

259
**Usage:**
260
```java
261
PhoenixConnection connection = getPhoenixConnection();
262
PMetaData metaData = connection.getMetaDataCache();
263

264
// Access table by key
265
PTableKey tableKey = new PTableKey(connection.getTenantId(), "users");
266
try {
267
    PTable table = metaData.getTableRef(tableKey).getTable();
268
    System.out.println("Found table: " + table.getName().getString());
269
} catch (TableNotFoundException e) {
270
    System.out.println("Table not found in cache");
271
}
272

273
// Iterate over all cached tables
274
for (PTable table : metaData) {
275
    System.out.println("Cached table: " + table.getName().getString());
276
}
277

278
// Check cache size and age
279
int cacheSize = metaData.size();
280
System.out.println("Metadata cache contains " + cacheSize + " tables");
281
```
282

283
## Common Usage Patterns
284

285
### Basic Table and Column Access
286

287
```java
288
PhoenixConnection connection = DriverManager.getConnection("jdbc:phoenix:localhost")
289
                                          .unwrap(PhoenixConnection.class);
290

291
// Get table metadata
292
PTable usersTable = connection.getTable("users");
293

294
// Examine table properties
295
System.out.println("Table: " + usersTable.getName().getString());
296
System.out.println("Type: " + usersTable.getType());
297
System.out.println("Columns: " + usersTable.getColumns().size());
298
System.out.println("PK Columns: " + usersTable.getPKColumns().size());
299

300
// Access specific columns
301
for (PColumn column : usersTable.getColumns()) {
302
    System.out.printf("Column: %s, Type: %s, Nullable: %s%n",
303
        column.getName().getString(),
304
        column.getDataType(),
305
        column.isNullable());
306
}
307
```
308

309
### Working with Primary Keys
310

311
```java
312
PTable table = connection.getTable("orders");
313
List<PColumn> pkColumns = table.getPKColumns();
314

315
System.out.println("Primary key columns:");
316
for (PColumn pkColumn : pkColumns) {
317
    System.out.printf("  %s (%s) - Position: %d, Sort: %s%n",
318
        pkColumn.getName().getString(),
319
        pkColumn.getDataType().toString(),
320
        pkColumn.getPosition(),
321
        pkColumn.getSortOrder());
322
}
323
```
324

325
### Index Analysis
326

327
```java
328
PTable baseTable = connection.getTable("users");
329
List<PTable> indexes = baseTable.getIndexes();
330

331
System.out.println("Indexes on " + baseTable.getName().getString() + ":");
332
for (PTable index : indexes) {
333
    System.out.printf("  Index: %s, State: %s, Type: %s%n",
334
        index.getName().getString(),
335
        index.getIndexState(),
336
        index.getType());
337

338
    // Show indexed columns
339
    List<PColumn> indexColumns = index.getColumns();
340
    for (PColumn col : indexColumns) {
341
        if (!col.getName().getString().startsWith("0:")) { // Skip row key columns
342
            System.out.println("    Column: " + col.getName().getString());
343
        }
344
    }
345
}
346
```
347

348
### Metadata Cache Operations
349

350
```java
351
PhoenixConnection connection = getConnection();
352
PMetaData originalCache = connection.getMetaDataCache();
353

354
// Force table metadata refresh
355
connection.getQueryServices().clearCache();
356

357
// Compare cache before and after
358
PMetaData refreshedCache = connection.getMetaDataCache();
359
System.out.println("Original cache size: " + originalCache.size());
360
System.out.println("Refreshed cache size: " + refreshedCache.size());
361
```