CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-apache-phoenix--phoenix-core

Apache Phoenix Core library providing SQL-on-HBase functionality with JDBC connectivity, query compilation, and transaction support

Overview
Eval results
Files

exceptions.mddocs/

Exception Handling

Phoenix provides a comprehensive exception hierarchy with detailed error codes, informative messages, and specific exception types for different error scenarios. The exception system helps developers identify and handle various database operation failures.

Core Imports

import org.apache.phoenix.exception.*;
import org.apache.phoenix.schema.*;
import java.sql.SQLException;

Exception Infrastructure

SQLExceptionCode

Enumeration of all Phoenix-specific SQL exception codes with standardized error messages and SQL states.

public enum SQLExceptionCode {
    // Connection and driver errors
    CANNOT_ESTABLISH_CONNECTION(101, "08001", "Unable to establish connection."),
    CONNECTION_CLOSED(102, "08003", "Connection is closed."),

    // Schema errors
    TABLE_NOT_FOUND(1012, "42M03", "Table '{0}' not found"),
    COLUMN_NOT_FOUND(504, "42703", "Undefined column. columnName={0}"),
    AMBIGUOUS_COLUMN(517, "42702", "Column reference '{0}' is ambiguous"),
    AMBIGUOUS_TABLE(519, "42702", "Table reference '{0}' is ambiguous"),

    // Data errors
    DATA_EXCEEDS_MAX_CAPACITY(201, "22001", "The value is outside the range for the data type"),
    CONSTRAINT_VIOLATION(1063, "23000", "Constraint violation. {0}"),
    TYPE_MISMATCH(203, "42821", "Type mismatch. {0}"),

    // Parsing errors
    PARSER_ERROR(601, "42P01", "Syntax error. {0}"),
    UNSUPPORTED_ORDER_BY_QUERY(1013, "0A000", "ORDER BY only allowed for queries with aggregate functions");

    public int getErrorCode()
    public String getSQLState()
    public String getMessage()
    public String toString()
}

SQLExceptionInfo

Builder and container for Phoenix SQL exception information with support for error chaining and context.

public class SQLExceptionInfo {
    // Static factory methods
    public static Builder newBuilder(SQLExceptionCode code)
    public static SQLExceptionInfo get(SQLExceptionCode code, Object... arguments)

    // Exception information
    public SQLExceptionCode getCode()
    public String getMessage()
    public String getSQLState()
    public int getErrorCode()
    public Throwable getRootCause()

    // Exception building
    public SQLException buildException()
    public SQLException buildException(SQLException rootCause)

    // Builder pattern
    public static class Builder {
        public Builder(SQLExceptionCode code)
        public Builder setMessage(String message)
        public Builder setRootCause(Throwable rootCause)
        public Builder setSchemaName(String schemaName)
        public Builder setTableName(String tableName)
        public Builder setColumnName(String columnName)
        public SQLExceptionInfo build()
    }
}

Usage:

// Create exception with builder pattern
SQLExceptionInfo.Builder builder = new SQLExceptionInfo.Builder(SQLExceptionCode.TABLE_NOT_FOUND);
builder.setTableName("users");
builder.setSchemaName("public");
SQLException exception = builder.build().buildException();

// Create exception directly
SQLException columnError = SQLExceptionInfo.get(
    SQLExceptionCode.COLUMN_NOT_FOUND, "email"
).buildException();

// Chain exceptions
try {
    // Some operation
} catch (SQLException cause) {
    SQLException chained = new SQLExceptionInfo.Builder(SQLExceptionCode.CONNECTION_CLOSED)
        .setRootCause(cause)
        .build()
        .buildException();
    throw chained;
}

Schema-Related Exceptions

TableNotFoundException

Exception thrown when a referenced table does not exist.

public class TableNotFoundException extends SQLException {
    public TableNotFoundException(String tableName)
    public TableNotFoundException(String schemaName, String tableName)
    public TableNotFoundException(PName name)

    public String getSchemaName()
    public String getTableName()
}

ColumnNotFoundException

Exception thrown when a referenced column does not exist.

public class ColumnNotFoundException extends SQLException {
    public ColumnNotFoundException(String columnName)
    public ColumnNotFoundException(String schemaName, String tableName, String columnName)

    public String getSchemaName()
    public String getTableName()
    public String getColumnName()
}

AmbiguousColumnException

Exception thrown when a column reference is ambiguous across multiple tables.

public class AmbiguousColumnException extends SQLException {
    public AmbiguousColumnException(String columnName)
    public AmbiguousColumnException(String columnName, List<String> tableNames)

    public String getColumnName()
    public List<String> getTableNames()
}

AmbiguousTableException

Exception thrown when a table reference is ambiguous.

public class AmbiguousTableException extends SQLException {
    public AmbiguousTableException(String tableName)
    public AmbiguousTableException(String tableName, List<String> schemaNames)

    public String getTableName()
    public List<String> getSchemaNames()
}

ColumnAlreadyExistsException

Exception thrown when attempting to create a column that already exists.

public class ColumnAlreadyExistsException extends SQLException {
    public ColumnAlreadyExistsException(String schemaName, String tableName, String columnName)

    public String getSchemaName()
    public String getTableName()
    public String getColumnName()
}

ColumnFamilyNotFoundException

Exception thrown when a referenced column family does not exist.

public class ColumnFamilyNotFoundException extends SQLException {
    public ColumnFamilyNotFoundException(String familyName)

    public String getFamilyName()
}

Usage:

try {
    // Attempt to access table
    PTable table = connection.getTable(PNameFactory.newName("nonexistent_table"));
} catch (TableNotFoundException e) {
    System.err.println("Table not found: " + e.getTableName());
    if (e.getSchemaName() != null) {
        System.err.println("Schema: " + e.getSchemaName());
    }
}

try {
    // Attempt to access column
    PColumn column = table.getColumn("nonexistent_column");
} catch (ColumnNotFoundException e) {
    System.err.println("Column not found: " + e.getColumnName());
    System.err.println("Table: " + e.getTableName());
}

try {
    // SQL with ambiguous column reference
    stmt.executeQuery("SELECT name FROM users, profiles");  // 'name' exists in both tables
} catch (AmbiguousColumnException e) {
    System.err.println("Ambiguous column: " + e.getColumnName());
    System.err.println("Found in tables: " + e.getTableNames());
}

Data and Constraint Exceptions

DataExceedsCapacityException

Exception thrown when data exceeds column capacity constraints (length, precision, etc.).

public class DataExceedsCapacityException extends SQLException {
    public DataExceedsCapacityException(String columnName, int maxCapacity, int actualSize)
    public DataExceedsCapacityException(PDataType dataType, Object value)

    public String getColumnName()
    public int getMaxCapacity()
    public int getActualSize()
    public PDataType getDataType()
}

ConstraintViolationException

Exception thrown when data violates table constraints (primary key, foreign key, check constraints).

public class ConstraintViolationException extends SQLException {
    public ConstraintViolationException(String constraintName)
    public ConstraintViolationException(String constraintName, String message)

    public String getConstraintName()
}

UndecodableByteException

Exception thrown when byte data cannot be decoded to the expected type.

public class UndecodableByteException extends SQLException {
    public UndecodableByteException(byte[] bytes, int offset, int length, PDataType expectedType)
    public UndecodableByteException(String message, Throwable cause)

    public byte[] getBytes()
    public int getOffset()
    public int getLength()
    public PDataType getExpectedType()
}

Usage:

try {
    // Insert data that exceeds VARCHAR(50) limit
    pstmt.setString(1, "This is a very long string that exceeds fifty characters");
    pstmt.executeUpdate();
} catch (DataExceedsCapacityException e) {
    System.err.println("Data too large for column: " + e.getColumnName());
    System.err.println("Maximum capacity: " + e.getMaxCapacity());
    System.err.println("Actual size: " + e.getActualSize());
}

try {
    // Insert duplicate primary key
    pstmt.setLong(1, 123);  // ID already exists
    pstmt.executeUpdate();
} catch (ConstraintViolationException e) {
    System.err.println("Constraint violation: " + e.getConstraintName());
    System.err.println("Message: " + e.getMessage());
}

try {
    // Attempt to decode invalid bytes as INTEGER
    byte[] invalidBytes = {0x01, 0x02};  // Wrong length for INTEGER
    Object value = PInteger.INSTANCE.toObject(invalidBytes, 0, 2);
} catch (UndecodableByteException e) {
    System.err.println("Cannot decode bytes as: " + e.getExpectedType().getSqlTypeName());
    System.err.println("Byte length: " + e.getLength());
}

Runtime and Parsing Exceptions

PhoenixNonRetryableRuntimeException

Runtime exception for non-retryable Phoenix errors that indicate programming or configuration issues.

public class PhoenixNonRetryableRuntimeException extends RuntimeException {
    public PhoenixNonRetryableRuntimeException(String message)
    public PhoenixNonRetryableRuntimeException(String message, Throwable cause)
    public PhoenixNonRetryableRuntimeException(Throwable cause)
}

PhoenixParserException

Exception thrown for SQL parsing errors with detailed syntax error information.

public class PhoenixParserException extends SQLException {
    public PhoenixParserException(String message)
    public PhoenixParserException(String message, Throwable cause)
    public PhoenixParserException(ParseException parseException)

    public int getLine()
    public int getColumn()
    public String getToken()
}

PhoenixIOException

Exception thrown for I/O related errors during Phoenix operations.

public class PhoenixIOException extends SQLException {
    public PhoenixIOException(IOException cause)
    public PhoenixIOException(String message, IOException cause)
    public PhoenixIOException(String message, Throwable cause)

    public IOException getIOException()
}

Usage:

try {
    // Parse invalid SQL
    String invalidSQL = "SELCT * FROM users";  // Typo in SELECT
    PreparedStatement stmt = connection.prepareStatement(invalidSQL);
} catch (PhoenixParserException e) {
    System.err.println("SQL parsing error at line " + e.getLine() + ", column " + e.getColumn());
    System.err.println("Token: " + e.getToken());
    System.err.println("Message: " + e.getMessage());
}

try {
    // Some configuration error
    throw new PhoenixNonRetryableRuntimeException("Invalid configuration: missing required property");
} catch (PhoenixNonRetryableRuntimeException e) {
    // This indicates a programming/configuration error, not a transient issue
    System.err.println("Non-retryable error: " + e.getMessage());
    // Fix configuration rather than retrying
}

try {
    // I/O operation fails
    connection.getQueryServices().getTable(tableName);
} catch (PhoenixIOException e) {
    IOException ioException = e.getIOException();
    System.err.println("I/O error: " + ioException.getMessage());
    // May be retryable depending on the underlying I/O error
}

High Availability and Failover Exceptions

FailoverSQLException

Exception thrown during connection failover scenarios in high availability setups.

public class FailoverSQLException extends SQLException {
    public FailoverSQLException(String message)
    public FailoverSQLException(String message, Throwable cause)
    public FailoverSQLException(String message, String sqlState, int errorCode)

    public boolean isRetryable()
    public long getRetryAfterMs()
}

Usage:

try {
    // Operation on failover connection
    ResultSet rs = stmt.executeQuery("SELECT * FROM users");
} catch (FailoverSQLException e) {
    if (e.isRetryable()) {
        long retryAfter = e.getRetryAfterMs();
        System.out.println("Failover occurred, retry after " + retryAfter + "ms");

        // Wait and retry
        Thread.sleep(retryAfter);
        ResultSet rs = stmt.executeQuery("SELECT * FROM users");
    } else {
        System.err.println("Non-retryable failover error: " + e.getMessage());
    }
}

System and Upgrade Exceptions

UpgradeRequiredException

Exception thrown when Phoenix system requires upgrade to handle current operations.

public class UpgradeRequiredException extends SQLException {
    public UpgradeRequiredException(String currentVersion, String requiredVersion)
    public UpgradeRequiredException(String message)

    public String getCurrentVersion()
    public String getRequiredVersion()
}

UpgradeNotRequiredException

Exception thrown when upgrade is attempted but not required.

public class UpgradeNotRequiredException extends SQLException {
    public UpgradeNotRequiredException(String currentVersion)

    public String getCurrentVersion()
}

UpgradeInProgressException

Exception thrown when upgrade is already in progress and concurrent operations are attempted.

public class UpgradeInProgressException extends SQLException {
    public UpgradeInProgressException(String message)
    public UpgradeInProgressException(long startTime, long estimatedDuration)

    public long getUpgradeStartTime()
    public long getEstimatedDuration()
    public long getRemainingTime()
}

Usage:

try {
    // Attempt operation that requires newer Phoenix version
    connection.createStatement().execute("CREATE TABLE ... WITH SOME_NEW_FEATURE");
} catch (UpgradeRequiredException e) {
    System.err.println("Phoenix upgrade required");
    System.err.println("Current version: " + e.getCurrentVersion());
    System.err.println("Required version: " + e.getRequiredVersion());
}

try {
    // Attempt to run upgrade when not needed
    PhoenixRuntime.upgradeSystemTables(connection);
} catch (UpgradeNotRequiredException e) {
    System.out.println("System is already up to date: " + e.getCurrentVersion());
}

try {
    // Attempt operation during upgrade
    ResultSet rs = stmt.executeQuery("SELECT * FROM SYSTEM.CATALOG");
} catch (UpgradeInProgressException e) {
    long remaining = e.getRemainingTime();
    System.out.println("Upgrade in progress, estimated remaining time: " + remaining + "ms");
}

Exception Handling Patterns

Comprehensive Exception Handling

public void executePhoenixOperation(Connection connection, String sql) {
    try {
        Statement stmt = connection.createStatement();
        ResultSet rs = stmt.executeQuery(sql);

        while (rs.next()) {
            // Process results
        }

    } catch (TableNotFoundException e) {
        System.err.println("Table does not exist: " + e.getTableName());
        // Create table or use different table

    } catch (ColumnNotFoundException e) {
        System.err.println("Column does not exist: " + e.getColumnName());
        // Modify query or alter table

    } catch (AmbiguousColumnException e) {
        System.err.println("Ambiguous column: " + e.getColumnName());
        System.err.println("Qualify column with table name");

    } catch (DataExceedsCapacityException e) {
        System.err.println("Data too large for column: " + e.getColumnName());
        System.err.println("Consider increasing column size or truncating data");

    } catch (ConstraintViolationException e) {
        System.err.println("Constraint violation: " + e.getConstraintName());
        // Handle duplicate keys, foreign key violations, etc.

    } catch (PhoenixParserException e) {
        System.err.println("SQL syntax error: " + e.getMessage());
        System.err.println("Position: line " + e.getLine() + ", column " + e.getColumn());

    } catch (FailoverSQLException e) {
        if (e.isRetryable()) {
            // Implement retry logic
            retryOperation(connection, sql, e.getRetryAfterMs());
        } else {
            System.err.println("Non-retryable failover error");
        }

    } catch (UpgradeRequiredException e) {
        System.err.println("System upgrade required: " + e.getRequiredVersion());
        // Trigger upgrade process

    } catch (SQLException e) {
        // Generic SQL exception handling
        System.err.println("SQL Error: " + e.getMessage());
        System.err.println("SQL State: " + e.getSQLState());
        System.err.println("Error Code: " + e.getErrorCode());

    } catch (Exception e) {
        System.err.println("Unexpected error: " + e.getMessage());
        e.printStackTrace();
    }
}

Custom Exception Creation

// Create custom exceptions with Phoenix exception framework
public class CustomPhoenixException extends SQLException {
    public CustomPhoenixException(String tableName, String operation) {
        super(SQLExceptionInfo.newBuilder(SQLExceptionCode.OPERATION_TIMED_OUT)
              .setTableName(tableName)
              .setMessage("Operation '" + operation + "' timed out")
              .build()
              .buildException());
    }
}

// Usage
throw new CustomPhoenixException("users", "bulk_insert");

Exception Information Extraction

public void analyzeException(SQLException e) {
    System.out.println("=== Exception Analysis ===");
    System.out.println("Message: " + e.getMessage());
    System.out.println("SQL State: " + e.getSQLState());
    System.out.println("Error Code: " + e.getErrorCode());

    // Check if it's a Phoenix-specific exception
    if (e instanceof TableNotFoundException) {
        TableNotFoundException tnfe = (TableNotFoundException) e;
        System.out.println("Missing table: " + tnfe.getTableName());
        if (tnfe.getSchemaName() != null) {
            System.out.println("Schema: " + tnfe.getSchemaName());
        }
    } else if (e instanceof ColumnNotFoundException) {
        ColumnNotFoundException cnfe = (ColumnNotFoundException) e;
        System.out.println("Missing column: " + cnfe.getColumnName());
        System.out.println("In table: " + cnfe.getTableName());
    } else if (e instanceof DataExceedsCapacityException) {
        DataExceedsCapacityException dece = (DataExceedsCapacityException) e;
        System.out.println("Capacity exceeded for: " + dece.getColumnName());
        System.out.println("Max capacity: " + dece.getMaxCapacity());
        System.out.println("Actual size: " + dece.getActualSize());
    }

    // Print stack trace for debugging
    Throwable cause = e.getCause();
    while (cause != null) {
        System.out.println("Caused by: " + cause.getMessage());
        cause = cause.getCause();
    }
}

Install with Tessl CLI

npx tessl i tessl/maven-org-apache-phoenix--phoenix-core

docs

configuration.md

exceptions.md

execution.md

expressions.md

index.md

jdbc.md

mapreduce.md

monitoring.md

query-compilation.md

schema-metadata.md

server.md

transactions.md

types.md

tile.json