or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client-operations.mddataset-management.mdindex.mdmetadata-operations.mdquery-execution.md
tile.json

tessl/maven-co-cask-cdap--cdap-explore-client

Java client interfaces for exploring and querying CDAP datasets using Apache Hive SQL with asynchronous execution and metadata operations.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/co.cask.cdap/cdap-explore-client@5.1.x

To install, run

npx @tessl/cli install tessl/maven-co-cask-cdap--cdap-explore-client@5.1.0

index.mddocs/

CDAP Explore Client

CDAP Explore Client provides Java interfaces for exploring and querying datasets within the Cask Data Application Platform (CDAP) using Apache Hive SQL. It offers both synchronous and asynchronous query execution capabilities, metadata exploration, and dataset management operations.

Package Information

  • Package Name: cdap-explore-client
  • Package Type: maven
  • Group ID: co.cask.cdap
  • Artifact ID: cdap-explore-client
  • Version: 5.1.2
  • Language: Java
  • Installation: Include in Maven dependencies or access via CDAP platform

Core Imports

import co.cask.cdap.explore.client.ExploreClient;
import co.cask.cdap.explore.client.ExploreFacade;
import co.cask.cdap.explore.service.Explore;
import co.cask.cdap.explore.client.ExploreExecutionResult;
import co.cask.cdap.explore.service.ExploreException;
import co.cask.cdap.common.UnauthenticatedException;
import co.cask.cdap.common.ServiceUnavailableException;

Common client implementations:

import co.cask.cdap.explore.client.DiscoveryExploreClient;
import co.cask.cdap.explore.client.FixedAddressExploreClient;

Basic Usage

import co.cask.cdap.explore.client.ExploreClient;
import co.cask.cdap.explore.client.ExploreExecutionResult;
import co.cask.cdap.proto.QueryResult;
import co.cask.cdap.proto.id.NamespaceId;
import com.google.common.util.concurrent.ListenableFuture;

// Initialize client (typically via dependency injection)
ExploreClient client = // obtained via Guice injection

// Execute SQL query asynchronously
NamespaceId namespace = new NamespaceId("default");
ListenableFuture<ExploreExecutionResult> future = 
    client.submit(namespace, "SELECT * FROM dataset_table LIMIT 10");

// Handle results
try {
    ExploreExecutionResult result = future.get();
    
    // Check if results are available
    if (result.canContainResults()) {
        // Iterate through results
        while (result.hasNext()) {
            QueryResult row = result.next();
            // Process row data
            System.out.println(row.toString());
        }
    }
    
    // Always close resources
    result.close();
} catch (Exception e) {
    // Handle exploration errors
    System.err.println("Query failed: " + e.getMessage());
}

Architecture

CDAP Explore Client is built around several key architectural components:

  • Client Layer: ExploreClient implementations providing HTTP-based communication with CDAP explore service
  • Service Interface: Explore interface defining the contract for Hive SQL operations
  • Result Handling: ExploreExecutionResult for streaming and managing query results
  • Service Discovery: Dynamic endpoint resolution via Twill service discovery
  • Facade Pattern: ExploreFacade providing simplified operations for common use cases
  • Dependency Injection: Guice-based configuration and client instantiation

Capabilities

Client Operations

Core client functionality for executing SQL queries, managing connections, and handling dataset operations. Provides both direct client interfaces and simplified facade patterns.

interface ExploreClient extends Closeable {
    void ping() throws UnauthenticatedException, ServiceUnavailableException, ExploreException;
    ListenableFuture<ExploreExecutionResult> submit(NamespaceId namespace, String statement);
    ListenableFuture<Void> enableExploreDataset(DatasetId datasetInstance);
    ListenableFuture<Void> disableExploreDataset(DatasetId datasetInstance);
}

Client Operations

Query Execution

Synchronous and asynchronous SQL query execution with comprehensive result handling, status monitoring, and resource management.

interface Explore {
    QueryHandle execute(NamespaceId namespace, String statement) throws ExploreException, SQLException;
    QueryStatus getStatus(QueryHandle handle) throws HandleNotFoundException, SQLException;
    List<QueryResult> nextResults(QueryHandle handle, int size) throws HandleNotFoundException, SQLException;
    void close(QueryHandle handle) throws HandleNotFoundException, SQLException;
}

Query Execution

Metadata Operations

Database metadata exploration including table discovery, column information, schema browsing, and catalog management.

interface Explore {
    QueryHandle getColumns(String catalog, String schemaPattern, 
                          String tableNamePattern, String columnNamePattern) throws ExploreException, SQLException;
    QueryHandle getTables(String catalog, String schemaPattern, 
                         String tableNamePattern, List<String> tableTypes) throws ExploreException, SQLException;
    List<TableNameInfo> getTables(String namespace) throws ExploreException, SQLException;
    TableInfo getTableInfo(String namespace, String table) throws ExploreException, SQLException, TableNotFoundException;
}

Metadata Operations

Dataset Management

Enable and disable exploration capabilities on CDAP datasets, manage partitions, and handle dataset lifecycle operations.

interface ExploreClient {
    ListenableFuture<Void> enableExploreDataset(DatasetId datasetInstance, 
                                               DatasetSpecification spec, boolean truncating);
    ListenableFuture<Void> updateExploreDataset(DatasetId datasetInstance, 
                                               DatasetSpecification oldSpec, DatasetSpecification newSpec);
    ListenableFuture<Void> addPartition(DatasetId datasetInstance, DatasetSpecification spec, 
                                       PartitionKey key, String path);
}

Dataset Management

Core Types

interface ExploreExecutionResult extends Iterator<QueryResult>, Closeable {
    List<ColumnDesc> getResultSchema() throws ExploreException;
    QueryStatus getStatus();
    boolean canContainResults();
    int getFetchSize();
    void setFetchSize(int fetchSize);
}

class QueryHandle {
    // Immutable handle for tracking query execution
}

class QueryStatus {
    public enum OpStatus { INITIALIZED, RUNNING, FINISHED, CANCELED, CLOSED, ERROR, UNKNOWN, PENDING }
    public OpStatus getStatus();
    public boolean hasResultSet();
}

class ColumnDesc {
    public String getName();
    public String getType();
    public int getPosition();
    public String getComment();
}

class QueryResult {
    public List<Object> getColumns();
}

class ExploreException extends Exception {
    public ExploreException(String message);
    public ExploreException(String message, Throwable cause);
}

class UnauthenticatedException extends Exception {
    // Exception thrown when the client is not authenticated
}

class ServiceUnavailableException extends Exception {
    // Exception thrown when the explore service is not available
}

class HandleNotFoundException extends Exception {
    public boolean isInactive();
}

class TableNotFoundException extends Exception {
    // Exception for table not found errors
}

class DatasetId {
    public DatasetId(String namespace, String dataset);
    public String getNamespace();
    public String getDataset();
}

class StreamId {
    public StreamId(String namespace, String stream);
    public String getNamespace();
    public String getStream();
}

class NamespaceId {
    public NamespaceId(String namespace);
    public String getNamespace();
}

class DatasetSpecification {
    public String getName();
    public String getType();
    public Map<String, String> getProperties();
}

class PartitionKey {
    public static Builder builder();
    public static class Builder {
        Builder addStringField(String name, String value);
        Builder addIntField(String name, int value);
        Builder addLongField(String name, long value);
        PartitionKey build();
    }
}

class FormatSpecification {
    public static Builder builder(String name);
    public String getName();
    public Schema getSchema();
    public static class Builder {
        Builder setSchema(Schema schema);
        FormatSpecification build();
    }
}

class NamespaceMeta {
    public NamespaceMeta(String name, String displayName, String description);
    public String getName();
    public String getDisplayName();
    public String getDescription();
}