Home Reference Source
import {SessionConfig} from 'neo4j-driver-core/lib/driver.js'
public interface | source

SessionConfig

The session configuration

Member Summary

Public Members
public

auth: AuthToken | undefined

The AuthToken which will be used for the duration of the session.

public

Configure a BookmarkManager for the session to use

since 5.0
public

bookmarks: string | string[] | undefined

The initial reference or references to some previous transactions.

public

database: string | undefined

The database this session will operate on.

public

The access mode of this session, allowed values are READ and WRITE.

public

fetchSize: number | undefined

The record fetch size of each batch of this session.

public

impersonatedUser: string | undefined

The username which the user wants to impersonate for the duration of the session.

public

Configure filter for Notification objects returned in ResultSummary#notifications.

since 5.7

Public Members

public auth: AuthToken | undefined source

The AuthToken which will be used for the duration of the session.

By default, the session will use connections authenticated with the AuthToken configured on driver creation. This configuration allows switching user and/or authorization information for the session lifetime.

Warning: This option is only available when the driver is connected to Neo4j Database servers which supports Bolt 5.1 or newer.

See:

public bookmarkManager: BookmarkManager | undefined since 5.0 source

Configure a BookmarkManager for the session to use

A BookmarkManager is a piece of software responsible for keeping casual consistency between different sessions by sharing bookmarks between the them. Enabling it is done by supplying an BookmarkManager implementation instance to this param. A default implementation could be acquired by calling the factory function bookmarkManager.

Warning: Sharing the same BookmarkManager instance across multiple sessions can have a negative impact on performance since all the queries will wait for the latest changes being propagated across the cluster. For keeping consistency between a group of queries, use Session for grouping them. For keeping consistency between a group of sessions, use BookmarkManager instance for grouping them.

Example:

const bookmarkManager = neo4j.bookmarkManager()
const linkedSession1 = driver.session({ database:'neo4j', bookmarkManager })
const linkedSession2 = driver.session({ database:'neo4j', bookmarkManager })
const unlinkedSession = driver.session({ database:'neo4j' })

// Creating Driver User
const createUserQueryResult = await linkedSession1.run('CREATE (p:Person {name: $name})', { name: 'Driver User'})

// Reading Driver User will *NOT* wait of the changes being propagated to the server before RUN the query
// So the 'Driver User' person might not exist in the Result
const unlinkedReadResult = await unlinkedSession.run('CREATE (p:Person {name: $name}) RETURN p', { name: 'Driver User'})

// Reading Driver User will wait of the changes being propagated to the server before RUN the query
// So the 'Driver User' person should exist in the Result, unless deleted.
const linkedResult = await linkedSession2.run('CREATE (p:Person {name: $name}) RETURN p', { name: 'Driver User'})

await linkedSession1.close()
await linkedSession2.close()
await unlinkedSession.close()

public bookmarks: string | string[] | undefined source

The initial reference or references to some previous transactions. Value is optional and absence indicates that that the bookmarks do not exist or are unknown.

public database: string | undefined source

The database this session will operate on.

This option has no explicit value by default, but it is recommended to set one if the target database is known in advance. This has the benefit of ensuring a consistent target database name throughout the session in a straightforward way and potentially simplifies driver logic as well as reduces network communication resulting in better performance.

Usage of Cypher clauses like USE is not a replacement for this option. The driver does not parse any Cypher.

When no explicit name is set, the driver behavior depends on the connection URI scheme supplied to the driver on instantiation and Bolt protocol version.

Specifically, the following applies:

  • bolt schemes - queries are dispatched to the server for execution without explicit database name supplied, meaning that the target database name for query execution is determined by the server. It is important to note that the target database may change (even within the same session), for instance if the user's home database is changed on the server.

  • neo4j schemes - providing that Bolt protocol version 4.4, which was introduced with Neo4j server 4.4, or above is available, the driver fetches the user's home database name from the server on first query execution within the session and uses the fetched database name explicitly for all queries executed within the session. This ensures that the database name remains consistent within the given session. For instance, if the user's home database name is 'movies' and the server supplies it to the driver upon database name fetching for the session, all queries within that session are executed with the explicit database name 'movies' supplied. Any change to the user’s home database is reflected only in sessions created after such change takes effect. This behavior requires additional network communication. In clustered environments, it is strongly recommended to avoid a single point of failure. For instance, by ensuring that the connection URI resolves to multiple endpoints. For older Bolt protocol versions the behavior is the same as described for the bolt schemes above.

public defaultAccessMode: string source

The access mode of this session, allowed values are READ and WRITE. Default: WRITE

public fetchSize: number | undefined source

The record fetch size of each batch of this session.

Use FETCH_ALL to always pull all records in one batch. This will override the config value set on driver config.

public impersonatedUser: string | undefined source

The username which the user wants to impersonate for the duration of the session.

public notificationFilter: NotificationFilter | undefined since 5.7 source

Configure filter for Notification objects returned in ResultSummary#notifications.

This configuration enables filter notifications by:

Disabling notifications can be done by defining the minimum severity level to 'OFF'. At driver level, when omitted, uses the server's default. At session level, when omitted, defaults to what filters have been configured at driver level.

Disabling categories or severities allows the server to skip analysis for those, which can speed up query execution.

Example:

// enabling warning notification, but disabling `HINT` and `DEPRECATION` notifications.
const session = driver.session({
    database: 'neo4j',
    notificationFilter: {
        minimumSeverityLevel: neo4j.notificationFilterMinimumSeverityLevel.WARNING, // or 'WARNING
        disabledCategories: [
            neo4j.notificationFilterDisabledCategory.HINT, // or 'HINT'
            neo4j.notificationFilterDisabledCategory.DEPRECATION // or 'DEPRECATION'
       ]
    }
})
// disabling notifications for a session
const session = driver.session({
    database: 'neo4j',
    notificationFilter: {
        minimumSeverityLevel: neo4j.notificationFilterMinimumSeverityLevel.OFF // or 'OFF'
    }
})
// using default values configured in the driver
const sessionWithDefaultValues = driver.session({ database: 'neo4j' })
// or driver.session({ database: 'neo4j', notificationFilter: undefined })

// using default minimum severity level, but disabling 'HINT' and 'UNRECOGNIZED'
// notification categories
const sessionWithDefaultSeverityLevel = driver.session({
    database: 'neo4j',
    notificationFilter: {
        disabledCategories: [
            neo4j.notificationFilterDisabledCategory.HINT, // or 'HINT'
            neo4j.notificationFilterDisabledCategory.UNRECOGNIZED // or 'UNRECOGNIZED'
       ]
    }
})

// using default disabled categories, but configuring minimum severity level to 'WARNING'
const sessionWithDefaultSeverityLevel = driver.session({
    database: 'neo4j',
    notificationFilter: {
        minimumSeverityLevel: neo4j.notificationFilterMinimumSeverityLevel.WARNING // or 'WARNING'
    }
})