WOLFRAM

Wolfram Language & System Documentation Center
Wolfram Language Home Page »

PersistentValue

As of Version 12.3, PersistentValue has been renamed PersistentSymbol.

✖
PersistentValue["name"]

represents the persistent value associated with the key "name".

✖
PersistentValue["name",loc]

represents the persistent value associated with name stored in persistence location loc.

✖
PersistentValue["name",{loc1,…}]

represents the persistent value associated with name at the first of the locations loci at which it occurs.

Details and Options

  • PersistentValue["name",…] evaluates to give the corresponding persistent value.
  • PersistentValue["name",…]=value sets a persistent value.
  • PersistentValue allows the following options:
  • MergingFunction Automaticthe function applied to the list of values found
    ValuePreprocessingFunction Identitythe function applied to new values to be assigned
    ExpirationDate Nonewhen the value should expire
    PersistenceTime Nonehow long the value should persist
  • In PersistentValue["name",loc], possible forms for the persistence location loc include:
  • PersistenceLocation["type"]"Local", "Cloud", "FrontEndSession", etc. locations
    "type"equivalent to PersistenceLocation["type"]
    PersistenceLocation["type","base"]location with a particular base (directory etc.)
    "type""base"equivalent to PersistenceLocation["type","base"]
  • Supported location types include:
  • "KernelSession"current invocation of the Wolfram Language kernel
    "FrontEndSession"current invocation of the Wolfram Notebook front end
    "Notebook"the notebook in which the current evaluation is being done
    "ServerSession"persistence for requests on a single web server
    "CookieManaged"persistence based on a Wolfram browser cookie
    "Local"local to a computer, based on user home directory
    "LocalShared"local to a computer, based on $BaseDirectory
    "Cloud"in the cloud defined by the current $CloudBase
    "Installation"installation defaults
  • PersistentValue["name"] is equivalent to PersistentValue["name",$PersistencePath].
  • PersistentValue["name"]=value is equivalent to PersistentValue["name",$PersistenceBase]=value.
  • PersistentValue["name",loc] is essentially PersistentObject["name",loc]["Value"].
  • When a single persistence location is specified, as in PersistentValue["name",loc,…], the setting for MergingFunction is not used.
  • Otherwise, with the setting MergingFunction->f, the final value returned is the result of applying the function f to the list of values found at all persistence locations.
  • Unless specified otherwise by "MergingFunction" metadata in the PersistentObject, MergingFunction->Automatic is equivalent to MergingFunction->First.
  • Before a new value is assigned in PersistentValue[sym]=value, any specified value preprocessing function is applied to value before the value is assigned.
  • If the preprocessing function returns $Failed, the assignment is not performed.
  • If no explicit setting for ValuePreprocessingFunction is given, the setting to use is looked up on $PersistencePath.
  • An expired persistent value is treated as nonexistent, and the underlying persistent object may be removed.
  • Persistent values can be removed with Remove. Remove[PersistentValue["name"]] is equivalent to Remove[PersistentValue["name",$PersistenceBase]].

Examples

open allclose all

Basic Examples  (3)Summary of the most common use cases

Assign a persistent value:

In[1]:=1
✖
https://wolfram.com/xid/0fq5yk6iujwoq-zfd0wp
Out[1]=1

Retrieve a previously saved value:

In[2]:=2
✖
https://wolfram.com/xid/0fq5yk6iujwoq-jy2s2b
Out[2]=2

Remember a value with front end session scope:

In[1]:=1
✖
https://wolfram.com/xid/0fq5yk6iujwoq-0oic9b

Use the saved value, even in a newly restarted kernel within the same front end session:

In[2]:=2
✖
https://wolfram.com/xid/0fq5yk6iujwoq-kemrac

Store values for the same name at different persistence locations:

In[1]:=1
✖
https://wolfram.com/xid/0fq5yk6iujwoq-y67lle

Retrieve the first value found:

In[2]:=2
✖
https://wolfram.com/xid/0fq5yk6iujwoq-70vj2x
Out[2]=2

Retrieve the list of all values on $PersistencePath:

In[3]:=3
✖
https://wolfram.com/xid/0fq5yk6iujwoq-qrlgbe
Out[3]=3

Options  (8)Common values & functionality for each option

MergingFunction  (3)

Create a complement of persistent values with key "lval" at various locations:

In[1]:=1
✖
https://wolfram.com/xid/0fq5yk6iujwoq-cqxfrv

List all existing values for the key "lval" on $PersistencePath:

In[2]:=2
✖
https://wolfram.com/xid/0fq5yk6iujwoq-bvu4r6
Out[2]=2

By default, only the first value is returned:

In[3]:=3
✖
https://wolfram.com/xid/0fq5yk6iujwoq-7kqeo9
Out[3]=3

Join and flatten all sublists:

In[4]:=4
✖
https://wolfram.com/xid/0fq5yk6iujwoq-r8u53h
Out[4]=4

Join all sublists:

In[5]:=5
✖
https://wolfram.com/xid/0fq5yk6iujwoq-hpk530
Out[5]=5

Create a complement of persistent associations with name "aval" at various locations:

In[1]:=1
✖
https://wolfram.com/xid/0fq5yk6iujwoq-otm1fh

List all existing values on $PersistencePath:

In[2]:=2
✖
https://wolfram.com/xid/0fq5yk6iujwoq-ode0vg
Out[2]=2

Merge the values of identical keys in the associations:

In[3]:=3
✖
https://wolfram.com/xid/0fq5yk6iujwoq-wy6rat
Out[3]=3

Define a default value for "mylist" with a custom merging function:

In[1]:=1
✖
https://wolfram.com/xid/0fq5yk6iujwoq-0kbfum

Define additional values at different persistence locations:

In[2]:=2
✖
https://wolfram.com/xid/0fq5yk6iujwoq-2c29n1

For looking up values, the custom merging function is now used:

In[3]:=3
✖
https://wolfram.com/xid/0fq5yk6iujwoq-0kusfb
Out[3]=3

PersistenceTime  (2)

Define a persistent value that expires in 5 seconds:

In[1]:=1
✖
https://wolfram.com/xid/0fq5yk6iujwoq-feydku

After 5 seconds, it is no longer used:

In[2]:=2
✖
https://wolfram.com/xid/0fq5yk6iujwoq-64fdyh
Out[2]=2
Out[2]=2

Define a persistent object that expires in 5 days:

In[1]:=1
✖
https://wolfram.com/xid/0fq5yk6iujwoq-gd6j5n

Verify the expiration date of the underlying persistent object:

In[2]:=2
✖
https://wolfram.com/xid/0fq5yk6iujwoq-3rai1q
Out[2]=2

ExpirationDate  (2)

Define a persistent value that expires at the beginning of the year 2020:

In[1]:=1
✖
https://wolfram.com/xid/0fq5yk6iujwoq-9fntf

Verify the expiration date of the underlying persistent object:

In[2]:=2
✖
https://wolfram.com/xid/0fq5yk6iujwoq-5zmt4q
Out[2]=2

Define a persistent value that expires at the beginning of next year:

In[1]:=1
✖
https://wolfram.com/xid/0fq5yk6iujwoq-j07py1

Verify the expiration date of the underlying persistent object:

In[2]:=2
✖
https://wolfram.com/xid/0fq5yk6iujwoq-v3isv9
Out[2]=2

ValuePreprocessingFunction  (1)

Define a value preprocessing function for a particular persistent value that accepts only integers:

In[1]:=1
✖
https://wolfram.com/xid/0fq5yk6iujwoq-wy7p8l
In[2]:=2
✖
https://wolfram.com/xid/0fq5yk6iujwoq-3vhtnm

Assign an integer at any persistence location:

In[3]:=3
✖
https://wolfram.com/xid/0fq5yk6iujwoq-4y9vyv

Assigning anything else generates an error and the assignment is not performed:

In[4]:=4
✖
https://wolfram.com/xid/0fq5yk6iujwoq-3p8rlt
In[5]:=5
✖
https://wolfram.com/xid/0fq5yk6iujwoq-8bwm3f
Out[5]=5

Applications  (1)Sample problems that can be solved with this function

List all existing persistent objects for the key "lval":

In[1]:=1
✖
https://wolfram.com/xid/0fq5yk6iujwoq-kbj5qe
Out[1]=1

Delete them:

In[2]:=2
✖
https://wolfram.com/xid/0fq5yk6iujwoq-4aeb7y

Properties & Relations  (5)Properties of the function, and connections to other functions

Persistent values are stored in persistent objects:

In[1]:=1
✖
https://wolfram.com/xid/0fq5yk6iujwoq-znxbp5
In[2]:=2
✖
https://wolfram.com/xid/0fq5yk6iujwoq-ykv2li
Out[2]=2

The default location of a new persistent object is given by $PersistenceBase:

In[1]:=1
✖
https://wolfram.com/xid/0fq5yk6iujwoq-0rorvd
In[2]:=2
✖
https://wolfram.com/xid/0fq5yk6iujwoq-53t88y
Out[2]=2

Create a complement of persistent values with key "v" at various locations:

In[1]:=1
✖
https://wolfram.com/xid/0fq5yk6iujwoq-otdl6x

Persistent values are by default searched on all locations given in $PersistencePath:

In[2]:=2
✖
https://wolfram.com/xid/0fq5yk6iujwoq-ynro40
Out[2]=2

The first value found is returned:

In[3]:=3
✖
https://wolfram.com/xid/0fq5yk6iujwoq-ktafgq
Out[3]=3

With MergingFunction->Identity, all values found are returned in a list:

In[4]:=4
✖
https://wolfram.com/xid/0fq5yk6iujwoq-fr72sg
Out[4]=4

Specify an explicit list of locations to search for values:

In[5]:=5
✖
https://wolfram.com/xid/0fq5yk6iujwoq-hyzsk4
Out[5]=5

Expiration times specified with PersistenceTime are converted to absolute expiration dates:

In[1]:=1
✖
https://wolfram.com/xid/0fq5yk6iujwoq-4wzuuj
In[2]:=2
✖
https://wolfram.com/xid/0fq5yk6iujwoq-omrh0l
Out[2]=2

Persistent values can be removed with Remove:

In[1]:=1
✖
https://wolfram.com/xid/0fq5yk6iujwoq-xeaxv2
In[2]:=2
✖
https://wolfram.com/xid/0fq5yk6iujwoq-blsooy
In[3]:=3
✖
https://wolfram.com/xid/0fq5yk6iujwoq-j8o8qt
Out[3]=3

Possible Issues  (1)Common pitfalls and unexpected behavior

Create two persistent values for "name" in different locations:

In[1]:=1
✖
https://wolfram.com/xid/0fq5yk6iujwoq-dhsrmc

Remove by default removes only the value in the location given by $PersistenceBase:

In[2]:=2
✖
https://wolfram.com/xid/0fq5yk6iujwoq-y8e29a
In[3]:=3
✖
https://wolfram.com/xid/0fq5yk6iujwoq-jdbo4p
Out[3]=3

Remove all values that might exist anywhere in the locations given by $PersistencePath:

In[4]:=4
✖
https://wolfram.com/xid/0fq5yk6iujwoq-6iica
In[5]:=5
✖
https://wolfram.com/xid/0fq5yk6iujwoq-3dvr9p
Out[5]=5
Wolfram Research (2017), PersistentValue, Wolfram Language function, https://reference.wolfram.com/language/ref/PersistentValue.html (updated 2019).
✖
Wolfram Research (2017), PersistentValue, Wolfram Language function, https://reference.wolfram.com/language/ref/PersistentValue.html (updated 2019).

Text

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

✖
Wolfram Research (2017), PersistentValue, Wolfram Language function, https://reference.wolfram.com/language/ref/PersistentValue.html (updated 2019).

CMS

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

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

APA

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

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

BibTeX

@misc{reference.wolfram_2025_persistentvalue, author="Wolfram Research", title="{PersistentValue}", year="2019", howpublished="\url{https://reference.wolfram.com/language/ref/PersistentValue.html}", note=[Accessed: 27-April-2025 ]}

✖
@misc{reference.wolfram_2025_persistentvalue, author="Wolfram Research", title="{PersistentValue}", year="2019", howpublished="\url{https://reference.wolfram.com/language/ref/PersistentValue.html}", note=[Accessed: 27-April-2025 ]}

BibLaTeX

@online{reference.wolfram_2025_persistentvalue, organization={Wolfram Research}, title={PersistentValue}, year={2019}, url={https://reference.wolfram.com/language/ref/PersistentValue.html}, note=[Accessed: 27-April-2025 ]}

✖
@online{reference.wolfram_2025_persistentvalue, organization={Wolfram Research}, title={PersistentValue}, year={2019}, url={https://reference.wolfram.com/language/ref/PersistentValue.html}, note=[Accessed: 27-April-2025 ]}