linkSessions

All Model and QueryRunner queries use a session in order to run. A session can be created by using the driver, or by using the getSession helper to help with running queries in the same session.

All Model queries can accept an existing session as a parameter. If it's given, every query will run in this session. If not, a new session will be created for the queries to run.

All QueryRunner queries require an existing session.

linkGetting a session from the driver

1link/* --> the driver can be obtained by the Neogma instance */

2linkconst driver = neogma.getDriver();

3link/* --> use the driver to create a session */

4linkconst session = driver.session();

5link/* --> this session can be used in more than one Neogma operations */

6linkawait Users.createOne(

7link    {

8link        id: '1',

9link        name: 'John'

10link    },

11link    {

12link        session

13link    }

14link);

15linkawait Users.findAll({

16link    session

17link});

18link/* --> the session can also be used in the QueryRunner. Let 'queryRunner' be a QueryRunner instance */

19linkawait queryRunner.run('RETURN 1 = 1', {}, session); // @see [QueryRunner](./QueryRunner/Overview)

20link/* --> closing the session */

21linkawait session.close();

linkGetting a session with the getSession helper

A session can also be obtained with the getSession helper. Its first parameter is an existing session: if it's set, it will be used as-is in the callback. Else, a new one will be created. Ιts second parameter is a callback with the session as the first parameter.

After the callback is done, the session automatically closes.

If getSession calls are nested, the session will close after all of them are done.

1linkawait getSession(

2link    /* --> no session is passed, so a new one will be created */

3link    null, 

4link    async (session) => {

5link        /* --> this session can be used in more than one Neogma operations */

6link        await Users.createOne(

7link            {

8link                id: '1',

9link                name: 'John'

10link            },

11link            {

12link                session

13link            }

14link        );

15link

16link        /* --> let's create a function that takes a session param */

17link        const myFindUser = (sessionParam) => {

18link            /* --> this param is used for a getSession. So, if it already exists, it will be used. Else, a new one will be created */

19link            await getSession(sessionParam, async (sessionToUse) => {

20link                /* --> we can perform multiple operations with this session */

21link                await Users.findAll({

22link                    session: sessionToUse

23link                });

24link                await Users.findOne({

25link                    session: sessionToUse

26link                });

27link                await queryRunner.run('RETURN 1 = 1', {}, sessionToUse);

28link            }, driver);

29link        };

30link

31link        /* --> no session is given, so the operations in 'myFindUser' will run in their own session */

32link        await myFindUser(null);

33link        /* --> the existing session is given, so the operations in 'myFindUser' will run using this existing session */

34link        await myFindUser(session);

35link    },

36link    /* --> a neo4j driver is needed */

37link    driver,

38link    {

39link        /* --> pass any other params, as you would for the driver's `session` method */

40link        database: "myDb"

41link    }

42link);

43link/* --> at this stage, the session will close */

As we can see, this helper is useful when we have to run multiple operations in a single session, but we want to easily allow an existing session to be used.

linkGetting a transaction from a session

An existing session can be used to create a transaction.

1link/* --> let 'session' be a session object, acquired by one of the above methods */

2linkconst transaction = session.beginTransaction();

3link/* --> this transaction can be used in more than one Neogma operations */

4linkawait Users.createOne(

5link    {

6link        id: '1',

7link        name: 'John'

8link    },

9link    {

10link        session: transaction

11link    }

12link);

13linkawait Users.findOne({

14link    session: transaction

15link});

16link/* --> commit the transaction */

17linkawait transaction.commit(); // or .rollback() to roll it back

linkGetting a transaction with the getTransaction helper

A transaction can also be obtained with the getTransaction helper. Its first parameter is an existing transaction or a session.

• If it's a transaction, it will be used as-is in the callback.
• Else, a new one will be created. If the first parameter is a session, it will be used to create the transaction. Ιts second parameter is a callback with the transaction as the first parameter.

After the callback is done, the transaction automatically gets commited and the session closes. In case an error is thrown, the transaction automatically gets rolled back.

If getTransaction calls are nested, the transaction will commit after all of them are done.

1linkawait getTransaction(

2link    /* --> no transaction is passed, so a new one will be created */

3link    null,

4link    async (transaction) => {

5link        /* --> this transaction can be used in more than one Neogma operations */

6link        await Users.createOne(

7link            {

8link                id: '1',

9link                name: 'John'

10link            },

11link            {

12link                session: transaction

13link            }

14link        );

15link

16link        /* --> getTransaction calls can be nested */

17link        await getTransaction(

18link            /* --> the existing transaction is used */

19link            transaction, 

20link            async (transactionToUse) => {

21link                /* --> we can perform multiple operations with this transaction */

22link                await Users.findAll({

23link                    session: transactionToUse

24link                });

25link                await Users.findOne({

26link                    session: transactionToUse

27link                });

28link                await queryRunner.run('RETURN 1 = 1', {}, transactionToUse);

29link            }

30link        );

31link    },

32link    /* --> a neo4j driver is needed */

33link    driver,

34link    {

35link        /* --> pass any other params, as you would for the driver's `session` method */

36link        database: "myDb"

37link    }

38link);

39link/* --> at this stage, the transaction will be committed */

As we can see, this helper is useful when we have to run multiple operations in a single transaction, but we want to easily allow an existing transaction to be used.

linkGetting a session or transaction with the getRunnable helper

The getRunnable helper can be used to acquire an existing transaction or session. If none is given, a new session will be created.

In case nothing is given:

1linkawait getRunnable(

2link    /* --> no runnable is passed, so a new session will be created */

3link    null,

4link    async (session) => {

5link        await queryRunner.run('RETURN 1 = 1', {}, session);

6link    },

7link    /* --> a neo4j driver is needed */

8link    driver,

9link    {

10link        /* --> pass any other params, as you would for the driver's `session` method */

11link        database: "myDb"

12link    }

13link);

In case a session is given:

1linkawait getRunnable(

2link    /* --> no runnable is passed, so a new session will be created */

3link    null,

4link    async (session) => {

5link        await queryRunner.run('RETURN 1 = 1', {}, session);

6link

7link        await getRunnable(

8link            /* --> a session is passed, so it will be used */

9link            session,

10link            async (sessionToUse) => {

11link                /* --> this runs in the same session as the other query */

12link                await queryRunner.run('RETURN 1 = 1', {}, sessionToUse);

13link            },

14link            driver

15link        );

16link    },

17link    driver,

18link);

In case a transaction is given:

1link/* --> let's create a transaction */

2linkawait getTransaction(

3link    null,

4link    async (transaction) => {

5link        await queryRunner.run('RETURN 1 = 1', {}, transaction);

6link

7link        await getRunnable(

8link            /* --> a transaction is passed, so it will be used */

9link            transaction,

10link            async (transactionToUse) => {

11link                /* --> this runs in the same transaction as the other query */

12link                await queryRunner.run('RETURN 1 = 1', {}, transactionToUse);

13link            },

14link            driver

15link        );

16link    },

17link    driver

18link);

As we can see, this helper gives us flexibility when we want to run queries no matter in a session or transaction, depending on what was given in parameters.

linkUsing neogma instance wrappers for these functions

A neogma instance also provides a wrapper of those functions, with the last parameter (the driver) being omitted.

1linkawait neogma.getSession(null, async (session) => {

2link    await Users.findOne({

3link        session

4link    });

5link});

6link

7linkawait neogma.getTransaction(null, async (transaction) => {

8link    await Users.findOne({

9link        session: transaction

10link    });

11link});

12link

13linkawait neogma.getRunnable(null, async (session) => {

14link    await Users.findOne({

15link        session

16link    });

17link});