StartExternalSession   

Listing of External Evaluators »

StartExternalSession["sys"]

starts an external session using the external evaluator sys, returning an external session object.

StartExternalSession[assoc]

starts the external evaluator specified by assoc.

StartExternalSession[{"sys",opts}]

uses the options opts for the external evaluator.

StartExternalSession[systype]

specifies that output from the external evaluator should be converted to the specified type.

StartExternalSession[DatabaseReference[ref]]

uses the database specified by ref to start a database session.

Details

  • StartExternalSession starts an external process that can be used to implement an external evaluator session in which there are multiple evaluations requested by ExternalEvaluate.
  • In StartExternalSession[assoc], elements of the association can include:
  • "System"the external system or language to start
    "Evaluator"the specific evaluator to execute code
    "Name"the registered name of an evaluator
    "ID"a unique identifier
    "ReturnType"type of object to return ("String", "Expression", ...)
    "Prolog"code to run before the command
    "Epilog"code to run after the command
    "SessionProlog"code to run before the session
    "SessionEpilog"code to run after the session
  • "System" is the only required key; all others are optional.
  • In StartExternalSession[sys], possible choices of sys include:
  • "Python"Python
    "NodeJS"JavaScript running through Node.js
    "Julia"Julia
    "Ruby"Ruby
    "R"R
    "Shell"Bash, Sh, Zsh, ...
    "Jupyter"Jupyter kernel
    "SQL"SQL database
    "SQL-JDBC"SQL database using JDBC
  • Possible settings for "type" in StartExternalSession[sys"type",…], or for "ReturnType", are dependent on the evaluation system, and typically include:
  • "Expression"attempt to convert to a Wolfram Language expression
    "String"give the raw string output by the external evaluator
  • The possible settings for evaluator in StartExternalSession[{sys,"Evaluator"evaluator},…] depend on sys, and include:
  • "path"path to a language executable
    DatabaseReference[…]an SQL database connection
    SQLConnection[…]an SQL-JDBC database connection
  • Typically, StartExternalSession uses the setting "ReturnType""Expression".
  • StartExternalSession[{"sys",opts}] is equivalent to StartExternalSession[<|"System""sys",opts|>].
  • StartExternalSession[{sys,"ID""id",…}] either returns an already running session with the given "id" or starts a new session with the unique "id".
  • FindExternalEvaluators gives a dataset of evaluator systems that can be used.
  • ExternalSessions gives a list of active external sessions.
  • DeleteObject[ExternalSessionObject[…]] kills and removes an external session started by StartExternalSession.

Examples

open allclose all

Basic Examples  (3)

Start an external Python session, automatically discovering any usable installations:

Evaluate code in the session:

Stop the session with DeleteObject:

Start a session using Python Version 3:

Verify the version:

End the session:

Start a new Python session in a provisioned environment:

Scope  (16)

Basic Uses  (2)

Multiple external sessions can be run simultaneously:

Delete the session objects:

Start an external Python session using the executable in /usr/bin/python3:

Use the session for multiple calls to ExternalEvaluate:

Stop the session with DeleteObject:

Session Options  (14)

"ReturnType"  (4)

For most systems, the default return type is "Expression":

Delete the session objects:

Numbers, strings, lists and associations are automatically imported for the "Expression" return type:

Delete the session objects:

The return type of "String" returns a string of the result in the external language:

Delete the session objects:

When using a database, the default return type is "Dataset":

"ReturnType" can be used to return data in a different form:

Delete the session objects:

"Evaluator"  (3)

Evaluate code using a specified "Evaluator":

Delete the session objects:

An Association can be used to start a Python provisioned environment:

Use the session to evaluate the code:

Delete the session objects:

When using a File with the "SQL" evaluator, the target can be a path to an SQLite file or a DatabaseReference specification:

Delete the session objects:

"Name"  (1)

Register an evaluator using a name:

Start a session using the registered evaluator by referring to it by name:

Use the session:

Close the session:

"ID"  (1)

Start an evaluator with a given "ID":

The operation is idempotent; starting a session with the same "ID" will return the same running session:

You can check that there is only one running session, even if you run StartExternalSession two times:

Close the session:

"SessionProlog"  (2)

Use "SessionProlog" to perform a side effect at the start of a session:

Delete the session objects:

Start an external session and import a library at the beginning of the session:

Evaluate a function from the imported library:

Delete the session object:

"SessionEpilog"  (1)

Use "SessionEpilog" to perform a side effect at the end of a session:

Delete the session object:

"Prolog"  (1)

Use "Prolog" to perform a side effect before every evaluation:

Delete the session object:

"Epilog"  (1)

Use "Epilog" to perform a side effect after every evaluation:

Delete the session object:

Properties & Relations  (4)

Each session runs in its own process:

The process IDs for each session are different:

Delete the session objects:

If only the language is specified, the first evaluator returned by FindExternalEvaluators is used:

Stop the session:

Start a database session:

Run a query:

Manually close the session:

External language cells implicitly call StartExternalSession:

x=2

A new session has been started:

By default, all cells of a given system use that session:

x*x

End the session so that subsequent evaluations start in a new session:

Wolfram Research (2017), StartExternalSession, Wolfram Language function, https://reference.wolfram.com/language/ref/StartExternalSession.html (updated 2024).

Text

Wolfram Research (2017), StartExternalSession, Wolfram Language function, https://reference.wolfram.com/language/ref/StartExternalSession.html (updated 2024).

CMS

Wolfram Language. 2017. "StartExternalSession." Wolfram Language & System Documentation Center. Wolfram Research. Last Modified 2024. https://reference.wolfram.com/language/ref/StartExternalSession.html.

APA

Wolfram Language. (2017). StartExternalSession. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/StartExternalSession.html

BibTeX

@misc{reference.wolfram_2024_startexternalsession, author="Wolfram Research", title="{StartExternalSession}", year="2024", howpublished="\url{https://reference.wolfram.com/language/ref/StartExternalSession.html}", note=[Accessed: 22-December-2024 ]}

BibLaTeX

@online{reference.wolfram_2024_startexternalsession, organization={Wolfram Research}, title={StartExternalSession}, year={2024}, url={https://reference.wolfram.com/language/ref/StartExternalSession.html}, note=[Accessed: 22-December-2024 ]}