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 |
bookmarkManager: BookmarkManager | undefined 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 |
defaultAccessMode: string |
|
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 |
notificationFilter: NotificationFilter | undefined 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
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:
- the minimum severity level (NotificationFilterMinimumSeverityLevel)
- disabling notification categories (NotificationFilterDisabledCategory)
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'
}
})