Package com.snowflake.snowpark_java

Class Session

  • public class Session
extends 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 DataFrames like Session.table, Session.sql, and Session.read
    Since:
    0.8.0
    See Also:
    DataFrame

    • 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​(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

      • table

        public Updatable table​(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​(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

      • removeDependency

        public void removeDependency​(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​(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 Set<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 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​(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​(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 Optional<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 Optional<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 Optional<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 Optional<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 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 Optional<String> getQueryTag()
        Returns the query tag that you set by calling setQueryTag.
        Returns:
        The current query tag
        Since:
        0.12.0

      • getSessionStage

        public 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,
                         String path,
                         boolean outer,
                         boolean recursive,
                         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 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,
                               Map<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​(String spName,
                                 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,
                                 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​(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