# populate

Populate an entity with a structure of name-value pairs. Make sure the names of the properties match the keys in the structure.

## Returns

* This function returns *the populated object*

## Arguments

| Key                  | Type    | Required | Default | Description                                                                                                      |
| -------------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| target               | any     | Yes      | ---     | The entity to populate                                                                                           |
| memento              | struct  | Yes      | ---     | The structure of name-value pairs to try to populate the entity with                                             |
| scope                | string  | No       |         | Use scope injection instead of setter injection, no need of setters, just tell us what scope to inject to        |
| trustedSetter        | Boolean | No       | false   | Do not check if the setter exists, just call it, great for usage with onMissingMethod() and virtual properties   |
| include              | string  | No       |         | A list of keys to ONLY include in the population                                                                 |
| exclude              | string  | No       |         | A list of keys to exclude from the population                                                                    |
| nullEmptyInclude     | string  | No       |         | A list of keys to NULL when empty, specifically for ORM population. You can also specify "\*" for all fields     |
| nullEmptyExclude     | string  | No       |         | A list of keys to NOT NULL when empty, specifically for ORM population. You can also specify "\*" for all fields |
| composeRelationships | boolean | No       | true    | When true, will automatically attempt to compose relationships from memento                                      |

> **INFO** With composeRelationships=true, you can populate one-to-many, many-to-one, many-to-many, and one-to-one relationships from property values in the memento. For 'many-to-one' and 'one-to-one' relationships, the value of the property in the memento should be a single value of the primary key of the target entity to be loaded. For 'one-to-many' and 'many-to-many' relationships, the value of the property in the memento should a comma-delimited list or array of the primary keys of the target entities to be loaded.

## Examples

```javascript
var user = ormService.populate( ormService.new("User"), data );

// populate with includes only
var user = ormService.populate( ormService.new("User"), data, "fname,lname,email" );

//populate with excludes
var user = ormService.populate(target=ormService.new("User"),memento=data,exclude="id,setup,total" );

// populate with null values when value is empty string
var user = ormService.populate(target=ormService.new("User"),memento=data,nullEmptyInclude="lastName,dateOfBirth" );

// populate many-to-one relationship
var data = {
    firstName = "Luis",
    role = 1 // "role" is the name of the many-to-one relational property, and one is the key value
};
var user = ormService.populate( target=ormService.new("User"), memento=data, composeRelationships=true );
// the role relationship will be composed, and the value will be set to the appropriate instance of the Role model

// populate one-to-many relationship
var data = {
    firstName = "Luis",
    favColors = "1,2,3" ( or [1,2,3] ) // favColors is the name of the one-to-many relational property, and 1, 2 and 3 are key values of favColor models
};
var user = ormService.populate( target=ormService.new("User"), memento=data, composeRelationships=true );
// the favColors property will be set to an array of favColor entities

// only compose some relationships
var data = {
    firstName = "Luis",
    role = 1,
    favColors = [ 1, 3, 19 ]
};
var user = ormService.populate( target=ormService.new("User"), memento=data, composeRelationships=true, exclude="favColors" );
// in this example, "role" will be composed, but "favColors" will be excluded
```


---

# Agent Instructions: 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://coldbox-orm.ortusbooks.com/v2.x-2/base-orm-service-1/service-methods/creation-population/populate.md?ask=<question>
```

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.