> For the complete documentation index, see [llms.txt](https://docs.rulecube.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rulecube.com/v2.5/how-to-guides/ruleset-development/entities/persisted-entities.md).
# Persisted Entities
## Introduction
Persisted Entities are Entities that can be stored in a database.
These entities have a defined lifecycle that typically includes creation, updates, and eventual deletion. Persisted Entities are crucial in applications where permanent data storage is necessary, enabling data retrieval and management across ruleset executions.
## Enabling persistency
Before you can use Persisted Entities, the Ruleset you're working in must be a Library and must have persistency enabled.
1. Open a new Ruleset and go to the Ruleset's Version Settings in the left menu
2. Check the 'Library' box
3. Check the 'Allow persistency' box
This will not automatically make any Entity a persisted one.
1. Create a new Entity
2. Check the 'Allow persistency' box
3. Save the Ruleset
This will change the Entity into a Persisted Entity.
## How to use
There are a few ways to store, retrieve, update and delete Persisted Entities:
* Programmatically
* Within a Ruleset
* Through the API (api/persisted-entity)
* Form data table (See [Create a Data table](/v2.5/how-to-guides/forms/create-a-data-table.md))
In this guide we will look at how to use Persisted Entities within a Ruleset.
## Saving an Entity
Let's start with creating a simple 'Person' entity.
### Creating the Person Entity
1. Create a new Ruleset
1. Check the 'Library' and 'Allow persistency' boxes under Version Settings
2. Create a new Entity named 'Person'
3. Add a 'FirstName' property of type `string`
4. Add a 'LastName' property of type `string`
5. Add a 'Birthdate' property of type `date`
6. Now, add a new Calculated Property named 'Age' with the following expression:\
`AGE(Birthdate)`
7. Finally, check the 'Allow persistency' box and save the Ruleset
### Saving an instance of the Person entity
1. Create a Rule named 'Test' with the following expression:
```csharp
let person1 = new Person({ FirstName: 'John', LastName: 'Doe', Birthdate: '1980-01-01' })
person1.save()
return Person.getAll().items
```
Let's analyze what this code does.
The first line creates a new instance of the Person Entity. This only creates an Entity as usual and does not yet save it to the database.
The second line actually stores the Person entity in the database.
The final line returns all Person entities currently in the database.
If we were to save the Ruleset and open it in the sandbox ("Try it out"), each time we will execute the Ruleset, it will create a new Person and the 'Test' rule's output will keep growing in size.
Before we do that, let's make it so the user can enter Person's name and birthdate via the Ruleset's input.
1. Create an Input named 'person1' of type 'Person'
2. Change the expression of the 'Test' Rule to:
```javascript
person1.save()
return Person.getAll().items
```
3. Save the Ruleset and click on "Try it out" at the top.
4. Enter some data into the input on the left
5. Execute the Ruleset
If you repeat steps 4-5, you will will notice how the output of the Test rule will increase until a size of 20 is reached.
This is because the `.getAll()` method is paginated and will only return 20 items each time it is called. To get to the other items we can either:
* Use a different page number (page 1, page 2, etc.)
* Use a different page size (return more items per page)
> See the [#static-methods](#static-methods "mention") section for more details on how to use `getAll()`.
Also note how the `Age` property is properly calculated for each entry in Test.
## Language reference
These are the methods available when using Persisted Entities programmatically. These are divided into: Instance Methods and Static Methods.
### Instance Methods
Instance methods are called on an instance of a Persisted Entity. These methods allow you to interact with the data and perform actions specific to a particular instance, such as saving changes, deleting the entity, or retrieving specific attributes.
| Method | Description |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| save() | Saves the instances. Can be used on new instances or to update an existing instance.
For instance, calling it twice in a row on a new instance will first create a new entry in the database, followed by updating it.
|
| delete() | Deletes the instance from the database. Only works on entities that already exist in the database. |
| setId(guid) | Sets the ID of the entity. Only useful in certain circumstances. Saving or fetching entities will automatically set the ID. |
| getId() | Returns the ID of the entity. |
### Static Methods
Static methods are called on the Entity class itself, not on a specific instance. These methods are useful for actions that do not pertain to a particular entity instance, such as creating a new entity, listing all entities, finding entities by certain criteria, or deleting multiple entities.
| Method | Description | | |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| getAll(meta, entityFilter)
meta: {
pageIndex: number,
pageSize: number,
sortBy: string
}
entityFilter: {
type: 'Equals' | 'And' | 'Or',
field: string,
value: any
}
| Gets all entity instances or filtered.
To get the first page of all instances:
Person.getAll()
To get up to 9999 instances at once:
Person.getAll({ pageSize: 9999 })
To get everybody named 'John':
Person.getAll({}, {
type: 'Equals',
field: 'FirstName',
value: 'John'
})
|
| get(id) | Gets a single instance by ID | | |
| save(entities) | Saves an array of entities and returns the saved instances. | | |
| delete(meta, entityFilter)
meta: {
createdFrom: date,
createdTo: date,
modifiedFrom: date,
modifiedTo: date
}
entityFilter: {
type: 'Equals' | 'And' | 'Or',
field: string,
value: any
}
| Deletes one or more instances.
To delete all instances:
Person.delete()
To delete all instances created after a certain date:
Person.delete({ createdFrom: '2025-01-01' })
To delete everybody named 'Doe':
Person.delete({}, {
type: 'Equals',
field: 'LastName',
value: 'Doe'
})
|
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.rulecube.com/v2.5/how-to-guides/ruleset-development/entities/persisted-entities.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.