Class Client

gRPC client for Spark Connect protocol.

Remarks

This class manages the gRPC connection to a Spark Connect server and provides methods for executing plans, analyzing plans, and managing configuration.

Resource Management:

  • The client maintains a persistent gRPC connection
  • Stream handlers are automatically registered for each request
  • Event listeners are managed per-request and cleaned up on stream completion
  • Call close to explicitly release resources when done

Stream Lifecycle:

  1. Stream created via makeServerStreamRequest
  2. Event listeners registered: 'data', 'error', 'status', 'end'
  3. Stream processes responses
  4. Listeners automatically removed on 'end' or 'error' events
  5. Promise resolves/rejects based on stream outcome

Error Handling:

  • All errors are converted using fromStatus
  • Streams handle both 'error' and 'status' events for comprehensive error reporting
  • Rejected promises propagate errors to callers

Example

const client = new Client(config);
try {
  const results = await client.execute(plan);
  // Process results
} finally {
  client.close(); // Clean up resources
}

Since

1.0.0

Constructors

constructor

Properties

conf_ client_ session_id_ user_context_ user_agent_ metadata_

Methods

builder analyze config

execution

execute

lifecycle

close

Constructors

constructor

Properties

conf_

conf_: Configuration

client_

client_: Client

session_id_

session_id_: string

user_context_

user_context_: UserContext

user_agent_

user_agent_: string = "spark-connect-js"

metadata_

metadata_: Metadata

Methods

Staticbuilder

analyze

config

execution

execute

  • execute(plan: Plan): Promise<ExecutePlanResponse[]>

    Executes a Spark plan and returns all response chunks.

    Parameters

    • plan: Plan

      The Spark execution plan to run

    Returns Promise<ExecutePlanResponse[]>

    Promise that resolves with array of all ExecutePlanResponse chunks

    Remarks

    This method creates a server-streaming gRPC call to execute a Spark plan.

    Stream Resource Management Pattern:

    // 1. Stream Creation
    const call = client.makeServerStreamRequest(...);

    // 2. Event Handler Registration
    call.on('data', handler);   // Collects responses
    call.on('error', handler);  // Handles errors
    call.on('status', handler); // Checks final status
    call.on('end', handler);    // Completes promise

    // 3. Automatic Cleanup
    // - On 'end': listeners removed, promise resolved
    // - On 'error': listeners removed, promise rejected
    // - Stream closed by gRPC automatically

    Resource Lifecycle:

    1. Creation: gRPC stream created, event listeners registered
    2. Processing: 'data' events accumulate responses in results array
    3. Completion:
      • Normal: 'end' event → resolve promise → listeners cleaned up
      • Error: 'error' event → reject promise → listeners cleaned up
      • Status error: 'status' event → reject promise → listeners cleaned up
    4. Cleanup: Stream closed by gRPC, event listeners garbage collected

    Memory Management:

    • Results array grows with each 'data' event
    • Stream reference held until Promise settles
    • Event handlers are closures over results array and Promise resolve/reject
    • All references released when Promise completes
    • No manual cleanup needed - managed by Promise lifecycle

    Error Handling:

    • Network errors → 'error' event → promise rejected
    • Protocol errors → 'status' event with non-OK code → promise rejected
    • All errors converted via fromStatus for consistent error handling

    Example

    const plan = createPlan();
    try {
      const responses = await client.execute(plan);
      responses.forEach(resp => processResponse(resp));
    } catch (error) {
      console.error('Execution failed:', error);
    }
    // Stream automatically cleaned up whether success or failure

lifecycle

close

  • close(): void

    Closes the underlying gRPC client and releases resources.

    Returns void

    Remarks

    This method should be called when the client is no longer needed to ensure proper cleanup of gRPC connections and prevent resource leaks.

    Resource Disposal:

    • Closes the gRPC channel
    • Releases any pending connections
    • Errors during close are logged but not thrown

    Important Notes:

    • After calling close(), the client cannot be reused
    • Any in-flight requests will be terminated
    • Safe to call multiple times (idempotent)

    Example

    const client = new Client(config);
    try {
      await client.execute(plan);
    } finally {
      client.close(); // Always clean up
    }

Settings

Member Visibility

On This Page

Constructors
Properties
Methods
execution
lifecycle