Session (Snowpark Java API Reference 1.20.0)

Package com.snowflake.snowpark_java

## Class Session

- java.lang.Object
- - com.snowflake.snowpark_java.Session

-     public class Session
      extends java.lang.Object

  Establishes a connection with a Snowflake database and provides methods for creating DataFrames and accessing objects for working with files in stages.

  When you create a `Session` object, you provide configuration settings to establish a connection with a Snowflake database (e.g. the URL for the account, a user name, etc.). You can specify these settings in a configuration file or in a Map that associates configuration setting names with values.

  To create a Session from a file:

       Session session = Session.builder().configFile("/path/to/file.properties").create();

  Session contains functions to construct `DataFrame`s like `Session.table`, `Session.sql`, and `Session.read`
  Since:
    0.8.0
  See Also:
    `DataFrame`

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addDependency​(java.lang.String path)` | Registers a file in stage or a local file as a dependency of a user-defined function (UDF).
    `static SessionBuilder` | `builder()` | Returns a builder you can use to set configuration properties and create a `Session` object.
    `void` | `cancelAll()` | Cancel all action methods that are running currently.
    `void` | `close()` | Close this session.
    `AsyncJob` | `createAsyncJob​(java.lang.String queryID)` | Returns an AsyncJob object that you can use to track the status and get the results of the asynchronous query specified by the query ID.
    `DataFrame` | `createDataFrame​(Row[] data, StructType schema)` | Creates a new DataFrame that uses the specified schema and contains the specified Row objects.
    `FileOperation` | `file()` | Returns a FileOperation object that you can use to perform file operations on stages.
    `DataFrame` | `flatten​(Column input)` | Creates a new DataFrame by flattening compound values into multiple rows.
    `DataFrame` | `flatten​(Column input, java.lang.String path, boolean outer, boolean recursive, java.lang.String mode)` | Creates a new DataFrame by flattening compound values into multiple rows.
    `DataFrame` | `generator​(long rowCount, Column... columns)` | Creates a new DataFrame via Generator function.
    `java.util.Optional<java.lang.String>` | `getCurrentDatabase()` | Returns the name of the current database for the JDBC session attached to this session.
    `java.util.Optional<java.lang.String>` | `getCurrentSchema()` | Returns the name of the current schema for the JDBC session attached to this session.
    `java.util.Optional<java.lang.String>` | `getDefaultDatabase()` | Returns the name of the default database configured for this session in `Session.builder`.
    `java.util.Optional<java.lang.String>` | `getDefaultSchema()` | Returns the name of the default schema configured for this session in `Session.builder`.
    `java.util.Set<java.net.URI>` | `getDependencies()` | Returns the list of URLs for all the dependencies that were added for user-defined functions (UDFs).
    `java.lang.String` | `getFullyQualifiedCurrentSchema()` | Returns the fully qualified name of the current schema for the session.
    `java.util.Optional<java.lang.String>` | `getQueryTag()` | Returns the query tag that you set by calling `setQueryTag`.
    `java.lang.String` | `getSessionInfo()` | Get the session information.
    `java.lang.String` | `getSessionStage()` | Returns the name of the temporary stage created by the Snowpark library for uploading and store temporary artifacts for this session.
    `java.sql.Connection` | `jdbcConnection()` | Returns the JDBC Connection object used for the connection to the Snowflake database.
    `DataFrame` | `range​(long end)` | Creates a new DataFrame from a range of numbers starting from 0.
    `DataFrame` | `range​(long start, long end)` | Creates a new DataFrame from a range of numbers.
    `DataFrame` | `range​(long start, long end, long step)` | Creates a new DataFrame from a range of numbers.
    `DataFrameReader` | `read()` | Returns a DataFrameReader that you can use to read data from various supported sources (e.g.
    `void` | `removeDependency​(java.lang.String path)` | Removes a path from the set of dependencies.
    `void` | `setQueryTag​(java.lang.String queryTag)` | Sets a query tag for this session.
    `SProcRegistration` | `sproc()` | Returns a SProcRegistration object that you can use to register Stored Procedures.
    `DataFrame` | `sql​(java.lang.String query)` | Returns a new `DataFrame` representing the results of a SQL query.
    `DataFrame` | `sql​(java.lang.String query, java.lang.Object... params)` | Returns a new `DataFrame` representing the results of a SQL query.
    `DataFrame` | `storedProcedure​(StoredProcedure sp, java.lang.Object... args)` | Creates a new DataFrame from the given Stored Procedure and arguments.
    `DataFrame` | `storedProcedure​(java.lang.String spName, java.lang.Object... args)` | Creates a new DataFrame from the given Stored Procedure and arguments.
    `Updatable` | `table​(java.lang.String name)` | Returns a Updatable that points to the specified table.
    `Updatable` | `table​(java.lang.String[] multipartIdentifier)` | Returns an Updatable that points to the specified table.
    `DataFrame` | `tableFunction​(Column func)` | Creates a new DataFrame from the given table function and arguments.
    `DataFrame` | `tableFunction​(TableFunction func, Column... args)` | Creates a new DataFrame from the given table function and arguments.
    `DataFrame` | `tableFunction​(TableFunction func, java.util.Map<java.lang.String,​Column> args)` | Creates a new DataFrame from the given table function and arguments.
    `UDAFRegistration` | `udaf()` | Returns a UDAFRegistration object that you can use to register UDAFs.
    `UDFRegistration` | `udf()` | Returns a UDFRegistration object that you can use to register UDFs.
    `UDTFRegistration` | `udtf()` | Returns a UDTFRegistration object that you can use to register UDTFs.
    `void` | `unsetQueryTag()` | Unset query_tag parameter for this session.
    `void` | `updateQueryTag​(java.lang.String queryTag)` | Updates the query tag that is a JSON encoded string for the current session.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### builder

          public static SessionBuilder builder()

      Returns a builder you can use to set configuration properties and create a `Session` object.
      Returns:
        A new `SessionBuilder` object.
      Since:
        0.8.0

    - #### sql

          public DataFrame sql​(java.lang.String query)

      Returns a new `DataFrame` representing the results of a SQL query.

      You can use this method to execute an arbitrary SQL statement.

      Parameters:
        `query` - The SQL statement to execute.
      Returns:
        A `DataFrame` object
      Since:
        0.8.0

    - #### sql

          public DataFrame sql​(java.lang.String query,
                               java.lang.Object... params)

      Returns a new `DataFrame` representing the results of a SQL query.

      You can use this method to execute an arbitrary SQL statement.

      Parameters:
        `query` - The SQL statement to execute.
        `params` - The binding parameters for SQL statement (optional)
      Returns:
        A `DataFrame` object
      Since:
        1.15.0

    - #### table

          public Updatable table​(java.lang.String name)

      Returns a Updatable that points to the specified table.

      `name` can be a fully qualified identifier and must conform to the rules for a Snowflake identifier.

      Parameters:
        `name` - Table name that is either a fully qualified name or a name in the current database/schema.
      Returns:
        A Updatable
      Since:
        0.12.0

    - #### table

          public Updatable table​(java.lang.String[] multipartIdentifier)

      Returns an Updatable that points to the specified table.

      `name` can be a fully qualified identifier and must conform to the rules for a Snowflake identifier.

      Parameters:
        `multipartIdentifier` - An array of strings that specify the database name, schema name, and table name.
      Returns:
        A Updatable
      Since:
        0.12.0

    - #### range

          public DataFrame range​(long end)

      Creates a new DataFrame from a range of numbers starting from 0. The resulting DataFrame has the column name "ID" and a row for each number in the sequence.
      Parameters:
        `end` - End of the range.
      Returns:
        A DataFrame
      Since:
        0.12.0

    - #### range

          public DataFrame range​(long start,
                                 long end,
                                 long step)

      Creates a new DataFrame from a range of numbers. The resulting DataFrame has the column name "ID" and a row for each number in the sequence.
      Parameters:
        `start` - Start of the range.
        `end` - End of the range.
        `step` - Step function for producing the numbers in the range.
      Returns:
        A DataFrame
      Since:
        0.12.0

    - #### range

          public DataFrame range​(long start,
                                 long end)

      Creates a new DataFrame from a range of numbers. The resulting DataFrame has the column name "ID" and a row for each number in the sequence.
      Parameters:
        `start` - Start of the range.
        `end` - End of the range.
      Returns:
        A DataFrame
      Since:
        0.12.0

    - #### createDataFrame

          public DataFrame createDataFrame​(Row[] data,
                                           StructType schema)

      Creates a new DataFrame that uses the specified schema and contains the specified Row objects.

      For example, the following code creates a DataFrame containing two columns of the types `int` and `string` with two rows of data:

      For example

           Row[] data = {Row.create(1, "a"), Row.create(2, "b")};
           StructType schema = StructType.create(
             new StructField("num", DataTypes.IntegerType),
             new StructField("str", DataTypes.StringType));
           DataFrame df = getSession().createDataFrame(data, schema);

      Parameters:
        `data` - An array of Row objects representing rows of data.
        `schema` - A StructType representing the schema for the DataFrame.
      Returns:
        A DataFrame
      Since:
        0.12.0

    - #### udf

          public UDFRegistration udf()

      Returns a UDFRegistration object that you can use to register UDFs.
      Returns:
        A UDF utility class, which contains UDF registration functions.
      Since:
        0.12.0

    - #### udtf

          public UDTFRegistration udtf()

      Returns a UDTFRegistration object that you can use to register UDTFs.
      Returns:
        A UDTFRegistration object that provides methods for registering UDTFs
      Since:
        1.4.0

    - #### udaf

          public UDAFRegistration udaf()

      Returns a UDAFRegistration object that you can use to register UDAFs.
      Returns:
        A UDAFRegistration object that provides methods for registering UDAFs
      Since:
        1.19.0

    - #### removeDependency

          public void removeDependency​(java.lang.String path)

      Removes a path from the set of dependencies.
      Parameters:
        `path` - Path to a local directory, local file, or file in a stage.
      Since:
        0.12.0

    - #### addDependency

          public void addDependency​(java.lang.String path)

      Registers a file in stage or a local file as a dependency of a user-defined function (UDF).

      The local file can be a JAR file, a directory, or any other file resource. If you pass the path to a local file to `addDependency`, the Snowpark library uploads the file to a temporary stage and imports the file when executing a UDF.

      If you pass the path to a file in a stage to `addDependency`, the file is included in the imports when executing a UDF.

      Note that in most cases, you don't need to add the Snowpark JAR file and the JAR file (or directory) of the currently running application as dependencies. The Snowpark library automatically attempts to detect and upload these JAR files. However, if this automatic detection fails, the Snowpark library reports this in an error message, and you must add these JAR files explicitly by calling `addDependency`.

      The following example demonstrates how to add dependencies on local files and files in a stage:

           session.addDependency("@my_stage/http-commons.jar")
           session.addDependency("/home/username/lib/language-detector.jar")
           session.addDependency("./resource-dir/")
           session.addDependency("./resource.xml")

      Parameters:
        `path` - Path to a local directory, local file, or file in a stage.
      Since:
        0.12.0

    - #### getDependencies

          public java.util.Set<java.net.URI> getDependencies()

      Returns the list of URLs for all the dependencies that were added for user-defined functions (UDFs). This list includes any JAR files that were added automatically by the library.
      Returns:
        A set of URI
      Since:
        0.12.0

    - #### cancelAll

          public void cancelAll()

      Cancel all action methods that are running currently. This does not affect on any action methods called in the future.
      Since:
        0.12.0

    - #### jdbcConnection

          public java.sql.Connection jdbcConnection()

      Returns the JDBC Connection object used for the connection to the Snowflake database.
      Returns:
        JDBC Connection object
      Since:
        0.12.0

    - #### setQueryTag

          public void setQueryTag​(java.lang.String queryTag)

      Sets a query tag for this session. You can use the query tag to find all queries run for this session.

      If not set, the default value of query tag is the Snowpark library call and the class and method in your code that invoked the query (e.g. `com.snowflake.snowpark.DataFrame.collect Main$.main(Main.scala:18)`).

      Parameters:
        `queryTag` - String to use as the query tag for this session.
      Since:
        0.12.0

    - #### unsetQueryTag

          public void unsetQueryTag()

      Unset query_tag parameter for this session.

      If not set, the default value of query tag is the Snowpark library call and the class and method in your code that invoked the query (e.g. `com.snowflake.snowpark.DataFrame.collect Main$.main(Main.scala:18)`).

      Since:
        0.12.0

    - #### updateQueryTag

          public void updateQueryTag​(java.lang.String queryTag)
                              throws com.snowflake.snowpark.SnowparkClientException

      Updates the query tag that is a JSON encoded string for the current session.

      Keep in mind that assigning a value via `setQueryTag(String)` will remove any current query tag state.

      Example 1:

           session.setQueryTag("{\"key1\":\"value1\"}");
           session.updateQueryTag("{\"key2\":\"value2\"}");
           System.out.println(session.getQueryTag().get());
           {"key1":"value1","key2":"value2"}

      Example 2:

           session.sql("ALTER SESSION SET QUERY_TAG = '{\"key1\":\"value1\"}'").collect();
           session.updateQueryTag("{\"key2\":\"value2\"}");
           System.out.println(session.getQueryTag().get());
           {"key1":"value1","key2":"value2"}

      Example 3:

           session.setQueryTag("");
           session.updateQueryTag("{\"key1\":\"value1\"}");
           System.out.println(session.getQueryTag().get());
           {"key1":"value1"}

      Parameters:
        `queryTag` - A JSON encoded string that provides updates to the current query tag.
      Throws:
        `com.snowflake.snowpark.SnowparkClientException` - If the provided query tag or the query tag of the current session are not valid JSON strings; or if it could not serialize the query tag into a JSON string.
      Since:
        1.13.0

    - #### generator

          public DataFrame generator​(long rowCount,
                                     Column... columns)

      Creates a new DataFrame via Generator function.

      For example:

           import com.snowflake.snowpark_java.Functions;
           DataFrame df = session.generator(10, Functions.seq4(),
             Functions.uniform(Functions.lit(1), Functions.lit(4), Functions.random()));

      Parameters:
        `rowCount` - The row count of the result DataFrame.
        `columns` - the column list of the result DataFrame
      Returns:
        A DataFrame
      Since:
        0.12.0

    - #### getDefaultDatabase

          public java.util.Optional<java.lang.String> getDefaultDatabase()

      Returns the name of the default database configured for this session in `Session.builder`.
      Returns:
        The name of the default database
      Since:
        0.12.0

    - #### getDefaultSchema

          public java.util.Optional<java.lang.String> getDefaultSchema()

      Returns the name of the default schema configured for this session in `Session.builder`.
      Returns:
        The name of the default schema
      Since:
        0.12.0

    - #### getCurrentDatabase

          public java.util.Optional<java.lang.String> getCurrentDatabase()

      Returns the name of the current database for the JDBC session attached to this session.

      For example, if you change the current database by executing the following code:

      `session.sql("use database newDB").collect();`

      the method returns `newDB`.

      Returns:
        The name of the current database for this session.
      Since:
        0.12.0

    - #### getCurrentSchema

          public java.util.Optional<java.lang.String> getCurrentSchema()

      Returns the name of the current schema for the JDBC session attached to this session.

      For example, if you change the current schema by executing the following code:

      `session.sql("use schema newSchema").collect();`

      the method returns `newSchema`.

      Returns:
        Current schema in session.
      Since:
        0.12.0

    - #### getFullyQualifiedCurrentSchema

          public java.lang.String getFullyQualifiedCurrentSchema()

      Returns the fully qualified name of the current schema for the session.
      Returns:
        The fully qualified name of the schema
      Since:
        0.12.0

    - #### getQueryTag

          public java.util.Optional<java.lang.String> getQueryTag()

      Returns the query tag that you set by calling `setQueryTag`.
      Returns:
        The current query tag
      Since:
        0.12.0

    - #### getSessionStage

          public java.lang.String getSessionStage()

      Returns the name of the temporary stage created by the Snowpark library for uploading and store temporary artifacts for this session. These artifacts include classes for UDFs that you define in this session and dependencies that you add when calling `addDependency`.
      Returns:
        The name of stage.
      Since:
        0.12.0

    - #### flatten

          public DataFrame flatten​(Column input)

      Creates a new DataFrame by flattening compound values into multiple rows.

      For example:

           import com.snowflake.snowpark_java.Functions;
           DataFrame df = session.flatten(Functions.parse_json(Functions.lit("{\"a\":[1,2]}")));

      Parameters:
        `input` - The expression that will be unseated into rows. The expression must be of data type VARIANT, OBJECT, or ARRAY.
      Returns:
        A DataFrame.
      Since:
        0.12.0

    - #### flatten

          public DataFrame flatten​(Column input,
                                   java.lang.String path,
                                   boolean outer,
                                   boolean recursive,
                                   java.lang.String mode)

      Creates a new DataFrame by flattening compound values into multiple rows.

      for example:

           import com.snowflake.snowpark_java.Functions;
           DataFrame df = session.flatten(Functions.parse_json(Functions.lit("{\"a\":[1,2]}")),
             "a", false. false, "BOTH");

      Parameters:
        `input` - The expression that will be unseated into rows. The expression must be of data type VARIANT, OBJECT, or ARRAY.
        `path` - The path to the element within a VARIANT data structure which needs to be flattened. Can be a zero-length string (i.e. empty path) if the outermost element is to be flattened.
        `outer` - If `false`, any input rows that cannot be expanded, either because they cannot be accessed in the path or because they have zero fields or entries, are completely omitted from the output. Otherwise, exactly one row is generated for zero-row expansions (with NULL in the KEY, INDEX, and VALUE columns).
        `recursive` - If `false`, only the element referenced by PATH is expanded. Otherwise, the expansion is performed for all sub-elements recursively.
        `mode` - Specifies which types should be flattened (`"OBJECT"`, `"ARRAY"`, or `"BOTH"`).
      Returns:
        A DataFrame.
      Since:
        0.12.0

    - #### close

          public void close()

      Close this session.
      Since:
        0.12.0

    - #### getSessionInfo

          public java.lang.String getSessionInfo()

      Get the session information.
      Returns:
        Session info
      Since:
        0.12.0

    - #### read

          public DataFrameReader read()

      Returns a DataFrameReader that you can use to read data from various supported sources (e.g. a file in a stage) as a DataFrame.
      Returns:
        A DataFrameReader
      Since:
        1.1.0

    - #### file

          public FileOperation file()

      Returns a FileOperation object that you can use to perform file operations on stages.
      Returns:
        A FileOperation object
      Since:
        1.2.0

    - #### tableFunction

          public DataFrame tableFunction​(TableFunction func,
                                         Column... args)

      Creates a new DataFrame from the given table function and arguments.

      Example

           session.tableFunction(TableFunctions.split_to_table(),
             Functions.lit("split by space"), Functions.lit(" "));

      Parameters:
        `func` - Table function object, can be created from TableFunction class or referred from the built-in list from tableFunctions.
        `args` - The arguments of the given table function.
      Returns:
        The result DataFrame
      Since:
        1.2.0

    - #### tableFunction

          public DataFrame tableFunction​(TableFunction func,
                                         java.util.Map<java.lang.String,​Column> args)

      Creates a new DataFrame from the given table function and arguments.

      Example

           Map<String, Column> args = new HashMap<>();
           args.put("input", Functions.parse_json(Functions.lit("[1,2]")));
           session.tableFunction(TableFunctions.flatten(), args);

      Parameters:
        `func` - Table function object, can be created from TableFunction class or referred from the built-in list from tableFunctions.
        `args` - function arguments map of the given table function. Some functions, like flatten, have named parameters. use this map to assign values to the corresponding parameters.
      Returns:
        The result DataFrame
      Since:
        1.2.0

    - #### tableFunction

          public DataFrame tableFunction​(Column func)

      Creates a new DataFrame from the given table function and arguments.

      Example

           session.tableFunction(TableFunctions.flatten(
             Functions.parse_json(df.col("col")),
             "path", true, true, "both"
           ));

      Parameters:
        `func` - Column object, which can be one of the values in the TableFunctions class or an object that you create from the `new TableFunction("name").call()`.
      Returns:
        The result DataFrame
      Since:
        1.10.0

    - #### sproc

          @PublicPreview
          public SProcRegistration sproc()

      Returns a SProcRegistration object that you can use to register Stored Procedures.
      Returns:
        A SProcRegistration object that provides methods for registering SProcs.
      Since:
        1.8.0

    - #### storedProcedure

          @PublicPreview
          public DataFrame storedProcedure​(java.lang.String spName,
                                           java.lang.Object... args)

      Creates a new DataFrame from the given Stored Procedure and arguments.

      Example

           session.storedProcedure("sp_name", "arg1", "arg2").show()

      Parameters:
        `spName` - The name of stored procedures.
        `args` - The arguments of the given stored procedure
      Returns:
        The result DataFrame
      Since:
        1.8.0

    - #### storedProcedure

          @PublicPreview
          public DataFrame storedProcedure​(StoredProcedure sp,
                                           java.lang.Object... args)

      Creates a new DataFrame from the given Stored Procedure and arguments.

      todo: add example in snow-683653

      Parameters:
        `sp` - The stored procedure object, can be created by `Session.sproc().register` methods.
        `args` - The arguments of the given stored procedure
      Returns:
        The result DataFrame
      Since:
        1.8.0

    - #### createAsyncJob

          public AsyncJob createAsyncJob​(java.lang.String queryID)

      Returns an AsyncJob object that you can use to track the status and get the results of the asynchronous query specified by the query ID.

      For example, create an AsyncJob by specifying a valid `query_id`, check whether the query is running or not, and get the result rows.

           AsyncJob job = session.createAsyncJob(id);
           Row[] result = job.getRows();

      Parameters:
        `queryID` - A valid query ID
      Returns:
        An AsyncJob object
      Since:
        1.2.0