Creating a Session Object

• host: optional. The server address to connect to.
• port: optional. The port number of the server.
• userid: optional. The username for server login.
• password: optional. The password for server login.

While creating the session, you can connect and log in to a DolphinDB server by specifying the server domain name/IP address, port number and user credentials.

import dolphindb as ddb

# create a session and connect to the local server
s = ddb.Session("localhost", 8848)

# create a session, connect to the local server, and login as user "admin"
s = ddb.Session("localhost", 8848, "admin", "123456")

Note

• host, port, userid, password can be left empty. You can establish the connection later after the session has been created.
• Even if the connection fails to establish due to incorrect parameter values, a session object will still be created.

bool, default False. Whether the session uses the SSL protocol for communication.

Example: Enable SSL protocol on the API client side

s = ddb.Session(enableSSL=True)

Note

• enableSSL is supported on DolphinDB server since version 1.10.17/1.20.6 or later.
• To enable the SSL protocol, the configuration parameter enableHTTPS must be set to true on the server side. For details, see the DolphinDB Manual - Secure Communication.

bool, default False. Whether the session enables asynchronous communication.

The asynchronous mode allows communication with the server only through the Session.run method, with no values being returned. With asynchronous communication enabled in the Python API, you can write data to the server without waiting for a response before proceeding to the next task.

Example: Enable asynchronous communication

s = ddb.Session(enableASYNC=True)

Note: Python API supports asynchronous communication parameter enableASYNC (formerly enableASYN in version 1.20.6.0) since version 1.30.19.1.

int, default 60. The duration (in unit of seconds) between two keepalive transmissions to detect the TCP connection status.

Example

 # set the keepalive time to 120 seconds 
s = ddb.Session(keepAliveTime=120)

Note:

• keepAliveTime is supported on Linux, Windows, and MacOS.
• For more information on setting the TCP connection timeout, see Session Methods.

bool, default False. Whether the session enables compressed communication.

Compressed communication can be a useful option when writing or querying large amounts of data. When compress is set to True, the data will be compressed before being transferred by the session, which can reduce bandwidth usage. Note that it increases the computational complexity on the server and API client, which may impact performance.

Example

import dolphindb.settings as keys

# enable compression when your API version >= 1.30.21.1
s = ddb.Session(compress=True, protocol=keys.PROTOCOL_DDB)

# enable compression when your API version <= 1.30.19.4
s = ddb.Session(compress=True, enablePickle=False)

Note

• compress is supported on DolphinDB server since version 1.30.6.
• If the DolphinDB Python API version you’re using is earlier than 1.30.21.1, enablePickle must be set to False. For API version 1.30.21.1 or later, protocol must be set to PROTOCOL_DDB. The following section explain the two parameters.

• protocol: protocol name, default PROTOCOL_DEFAULT (equivalent to PROTOCOL_DDB). The protocol for transferring data between the API client and the DolphinDB server.Note that for 3.0.1.1 and earlier Python API versions, the default protocol is PROTOCOL_PICKLE.

• enablePickle: bool, default True. Whether to use the pickle (PROTOCOL_PICKLE) as the protocol for transferring data between the API client and the DolphinDB server.

Note: If you have specified a protocol, it is recommended to avoid using enablePickle to prevent any potential conflicts.

Currently, the protocols PROTOCOL_DDB, PROTOCOL_PICKLE, and PROTOCOL_ARROW are supported. Protocols determine the format of data you receive after running DolphinDB scripts through Python API. For more information about the protocols, see Data Type Conversion.

Prior to the 1.30.21.1 version of DolphinDB Python API, you can choose whether to use PROTOCOL_PICKLE or PROTOCOL_DDB by specifying the enablePickle parameter.

Example

# use PROTOCOL_PICKLE
s = ddb.Session(enablePickle=True)

# use PROTOCOL_DDB
s = ddb.Session(enablePickle=False)

Starting from 1.30.21.1, the protocol parameter is provided for specifying the data format protocol. It can be PROTOCOL_DDB, PROTOCOL_PICKLE, or PROTOCOL_ARROW.

Example

import dolphindb.settings as keys

# use PROTOCOL_DDB
s = ddb.Session(protocol=keys.PROTOCOL_DDB)

# use PROTOCOL_PICKLE
s = ddb.Session(protocol=keys.PROTOCOL_PICKLE)

# use PROTOCOL_ARROW
s = ddb.Session(protocol=keys.PROTOCOL_ARROW)

bool, default false. Determines whether it is possible to configure the database chunk granularity during database creation.

enableChunkGranularityConfig controls whether the chunkGranularity parameter takes effect when the session.database function is called. If enableChunkGranularityConfig=False, chunkGranularity does not take effect in session.database().

Examples

In the following script, enableChunkGranularityConfig is set to True. chunkGranularity is effective in database().

import dolphindb as ddb
import dolphindb.settings as keys

# enableChunkGranularityConfig = True
s = ddb.Session("localhost", 8848, "admin", "123456", enableChunkGranularityConfig=True)

# chunkGranularity has taken effect
if s.existsDatabase("dfs://testdb"):
    s.dropDatabase("dfs://testdb")
db = s.database("db", partitionType=keys.VALUE, partitions=[1, 2, 3], dbPath="dfs://testdb", chunkGranularity="DATABASE")
print(s.run("schema(db)")["chunkGranularity"])

# the result is DATABASE

In the following script, enableChunkGranularityConfig is set to False. chunkGranularity does not take effect in database().

import dolphindb as ddb
import dolphindb.settings as keys

# enableChunkGranularityConfig = False
s = ddb.Session("localhost", 8848, "admin", "123456", enableChunkGranularityConfig=False)

# chunkGranularity does not take effect
if s.existsDatabase("dfs://testdb"):
    s.dropDatabase("dfs://testdb")
db = s.database("db", partitionType=keys.VALUE, partitions=[1, 2, 3], dbPath="dfs://testdb", chunkGranularity="TABLE")
print(s.run("schema(db)")["chunkGranularity"])

# the result is TABLE

bool, default False. Whether to enable the Python Parser feature.

Example

# enable python parser 
s = ddb.Session(python=True)

# disable python parser 
s = ddb.Session(python=False)

Note: This parameter will be supported in the upcoming version 3.00 of the DolphinDB server.

bool, default True. Determines whether to print content passed to the print() function in the terminal after executing the script.

Examples

# With show_output = True, print() content is shown
s = ddb.Session(show_output=True)
s.connect("localhost", 8848)
s.run("print(1);2")

# output
1
2

# With show_output = False, print() content is suppressed  
s = ddb.Session(show_output=False)
s.connect("localhost", 8848)
s.run("print(1);2")

# output
2

optional, default DolphinDB. The SQL dialect used when running scripts. Possible values are DolphinDB, Oracle, and MySQL.

Note: Oracle and MySQL dialects are supported in DolphinDB server versions 1.30.22/2.00.10 and higher.

To use this parameter, import the SqlStd enumeration class from dolphindb.settings before specifying it.

import dolphindb as ddb
from dolphindb.settings import SqlStd

s = ddb.Session(sqlStd=SqlStd.Oracle)