Package com.snowflake.snowpark_java

Class Session

java.lang.Object

com.snowflake.snowpark_java.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 Summary

Modifier and Type	Method	Description
void	addDependency(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(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, String path, boolean outer, boolean recursive, 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.
Optional<String>	getCurrentDatabase()	Returns the name of the current database for the JDBC session attached to this session.
Optional<String>	getCurrentSchema()	Returns the name of the current schema for the JDBC session attached to this session.
Optional<String>	getDefaultDatabase()	Returns the name of the default database configured for this session in Session.builder.
Optional<String>	getDefaultSchema()	Returns the name of the default schema configured for this session in Session.builder.
Set<URI>	getDependencies()	Returns the list of URLs for all the dependencies that were added for user-defined functions (UDFs).
String	getFullyQualifiedCurrentSchema()	Returns the fully qualified name of the current schema for the session.
Optional<String>	getQueryTag()	Returns the query tag that you set by calling setQueryTag.
String	getSessionInfo()	Get the session information.
String	getSessionStage()	Returns the name of the temporary stage created by the Snowpark library for uploading and store temporary artifacts for this session.
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(String path)	Removes a path from the set of dependencies.
void	setQueryTag(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(String query)	Returns a new DataFrame representing the results of a SQL query.
DataFrame	sql(String query, Object... params)	Returns a new DataFrame representing the results of a SQL query.
DataFrame	storedProcedure(StoredProcedure sp, Object... args)	Creates a new DataFrame from the given Stored Procedure and arguments.
DataFrame	storedProcedure(String spName, Object... args)	Creates a new DataFrame from the given Stored Procedure and arguments.
Updatable	table(String name)	Returns a Updatable that points to the specified table.
Updatable	table(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, Map<String,Column> args)	Creates a new DataFrame from the given table function and arguments.
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(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(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(String query,
                     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(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