Using the Planner

This documentation is for the upcoming 1.0 release. Therefore, the contents of this site are subject to change and may be inaccurate. If there are inaccuracies discovered, please submit a GitHub issue.

Who is this for?

If you have a use-case involving converting the PartiQL AST into PartiQL’s Logical Plan (and performing some processing on the plan), this may be for you. Common use-cases include:

  • Installing a catalog over your own data source (whether it be another database, a file system, etc) to the planner

  • Validating the semantic structure (plan) of a user’s query (after receiving the resolved plan)

  • Allow-listing or block-listing specific semantic features (after receiving the resolved plan)

High-Level Overview

The planner takes in an Abstract Syntax Tree (AST); resolves User-Defined Functions (UDFs), operators, and table references; and outputs a resolved Plan.

The planner is designed to act as a singleton in your application by taking in all required information via its parameters on the plan() method. Notably, the planner makes all of its typing judgements via the Session, which holds references to the registered Catalogs. In order to make sure the planner can resolve UDFs, tables, operators, and more, please make sure that you correctly implement and register a catalog (see Implementing a Catalog).

Installation

build.gradle.kts
dependencies {
    implementation("org.partiql:partiql-planner:1.0.0")
}

Usage

In the below example, we will create a planner, create a session, register catalogs, set the current user, set the current catalog, set the current namespace (schema), and convert the AST’s Statement into a resolved Plan.

Your Application Code
import org.partiql.ast.Statement
import org.partiql.plan.PartiQLPlan
import org.partiql.planner.PartiQLPlanner
import org.partiql.spi.catalog.Session

fun plan(statement: Statement, catalog: Catalog) {
    // Instantiate the planner
    val planner: PartiQLPlanner = PartiQLPlanner.standard()

    // Initialize a Session
    val session: Session = Session.builder()
        .identity("my_current_user_name") // Sets the CURRENT_USER
        .catalogs(catalog) // Registers all available catalogs (the single catalog in this case)
        .catalog(catalog.getName()) // Sets the current catalog
        .namespace(Namespace.of("some_schema")) // Sets the current namespace within the current catalog.
        .build()

    // Plan
    val plannerResult: PartiQLPlanner.Result = planner.plan(statement, session)
    val plan: PartiQLPlan = planernResult.getPlan()

    // Application-specific code
    analyzeAndTransformPlan(plan)
}

Error Handling

The planner also has a method, plan(Statement, Session, Context), that is used to provide a customized error-handling experience. Please see the Error Handling User Guide for more information.

Further Reading