Class: Entity

.xsds. Entity

new Entity(skeleton)

Creates new instance for entity.

NOTE: The Entity class described in this document is a placeholder for individual entity constructors returned by the $importEntity and $defineEntity functions, respectively. XSDS provides no actual class Entity; please replace Entity by the name of your constructor function!

Parameters:
Name Type Description
skeleton object Initial values for new instance.

Methods

<static> Entity.$build() → {object}

Creates entity instance from unmanaged value.

Similar to new, but also recursively builds associated instances using unmanaged value supplied.

Returns:
Instance build from unmanaged value.
Type
object

<static> Entity.$delete(condition)

Deletes from database, unmanaged.

Deletes instances matching condition on database, bypassing entity cache.

Parameters:
Name Type Description
condition object Filter condition for instances to delete on database.

<static> Entity.$deriveEntity(mapping, options) → {sap.hana.xs.libs.dbutils.xsds.Entity}

Defines ad-hoc entity based on previous import.
Parameters:
Name Type Argument Description
mapping object Additional mapping for new entity.
options object <optional>
Field mapping as described by $importEntity.
Returns:
New entity constructor.
Type
sap.hana.xs.libs.dbutils.xsds.Entity

<static> Entity.$discardAll(instances)

Batch discards multiple instances.
Parameters:
Name Type Description
instances object[] Array of entity instances to discard.
Example
SoHeader.$discardAll([myOrder1, myOrder2, myOrder3]);

<static> Entity.$field(name) → {object}

Returns a reference to a field of an entity to be used in $where, $addFields, $order, see {sap.hana.xs.libs.dbutils.xsds.Query} API.
Parameters:
Name Type Description
name string The name of the field.
Returns:
A reference to a field.
Type
object

<static> Entity.$find(condition) → {object}

Retrieves arbitrary entity instance matching given condition.

Returns null if no instance was found.

Parameters:
Name Type Argument Description
condition object <optional>
Structured conditional expression.
Returns:
Arbitrary instance matching condition, or null.
Type
object
Example
var myItem = SoItem.$find({ BILLINGSTATUS: "X" });

<static> Entity.$findAll(condition, limit) → {object}

Retrieves all entity instances matching given condition.

The filter condition is a nested object whose structure follows the structure of the entity. For each entity field, the condition may specify one or more expressions that compare the field to some value:


{ field: { op: value, [...] } }

Supported comparison operators op are $eq (equal), $ne (not equal), $lt (less than), $le (less than or equal), $gt (greater than), $ge (greater than or equal), $like, $unlike (not like), $null (is null/is not null), and $empty (empty/non-empty association).

Individual comparisons are joined by logical-and. Tests for equality field: { $eq: value } may be abbreviated to field: value.

For associations, properties may be compared to instances directly, i.e., { assocProp: instance }. Applying operators to instances is not supported.

For CDS Decimal types, the native JavaScript type is String in order to keep compatibility with the low-level database API. When comparing decimals using $lt, $le, $gt, or $ge, however, XSDS will convert both values to JavaScript numbers. Be advised that this may lead to rounding errors! Tests for equality $eq and inequality $ne always work on the string representation to avoid potential loss of information. Thus, make sure to use the correct string representation when supplying literals for decimal numbers, e.g., "100" vs. "1.0e2".

For CDS Date types, no conversions are performed. In particular, saving a JavaScript Date object to a CDS Date type will set the time to 00:00:00:000 on the database. Thus, when comparing dates, ensure that the reference date has the time set to 00:00:00:000. (Analoguous restrictions apply to CDS SecondDate types.)

If the condition is empty or missing, then all instances will be returned.

Filter conditions are limited in their expressiveness. For general conditions, the Query API can be used (see sap.hana.xs.libs.dbutils.xsds.Query for details).

Parameters:
Name Type Argument Description
condition object <optional>
Structured conditional expression.
limit integer <optional>
Upper limit on number of instances to retrieve.
Returns:
Array-like object with all instances matching condition.
Type
object
Examples
var order = SOHeader.$findAll({ TAXAMOUNT: { $gt: 100.0, $lt: "200.00" },
                                CURRENCY: { $null: false },
                                HISTORY: { CREATEDAT: { $gt: new Date() } } });
var order = SOHeader.$findAll({ items: { $empty: false } });

<static> Entity.$get(key) → {object}

Retrieves entity instance by unique key.

Retrieves instance with given key from entity cache or database. Returns null if no instance was found.

Parameters:
Name Type Description
key nested key
Returns:
Instance with given key, or null.
Type
object
Example
var myItem = SoItem.$get({ SALESORDERID: "01", SALESORDERITEM: "02" });

<static> Entity.$query() → {sap.hana.xs.libs.dbutils.xsds.Query}

Returns query object for the entity which can be refined and executed using the {sap.hana.xs.libs.dbutils.xsds.Query} API.
Returns:
A query object which retrieves all local fields of this entity upon execution.
Type
sap.hana.xs.libs.dbutils.xsds.Query

<static> Entity.$saveAll(instances)

Batch persists multiple instances.
Parameters:
Name Type Description
instances object[] Array of entity instances to persist.
Example
SoHeader.$saveAll([myOrder1, myOrder2, myOrder3]);

<static> Entity.$select(condition, options) → {object}

Reads from database, unmanaged.

Selects unmanaged values from the database, bypassing the entity cache. Returns unmanaged value object instead of entity instance. Convenience function for executing $query.

Parameters:
Name Type Argument Description
condition object Filter condition for selecting values.
options object <optional>
Select options passed to $query.
Properties
Name Type Argument Description
$factorized boolean <optional>
Factorized or flat result object.
Returns:
Unmanaged values matching filter condition.
Type
object

<static> Entity.$upsert(data)

Upserts into database, unmanaged.

Upserts unmanaged values into database, bypassing the entity cache. Convenience function for executing $query.

Parameters:
Name Type Description
data object Value object to upsert into database.

<static> Entity#$clone() → {object}

Creates unmanaged value from managed entity instance.

Creates a deep copy of the instance, but shares functions and native type objects, such as Dates.

Returns:
Detached, unmanaged copy of the entity instance.
Type
object

<static> Entity#$discard()

Discard entity instance and delete data from database.

Also discards associated instances if $cascadeDiscard property is set.

Example
var myItem = SoItem.$get({ SALESORDERID: "01", SALESORDERITEM: "02" });
myItem.$discard();

<static> Entity#$save() → {boolean}

Persists entity instance and all of its associated instances to the database.

In case of failure, the function may return with false or pass through any exception thrown by the database.

Returns:
true if successful.
Type
boolean
Example
var myItem = SoItem.$get({ SALESORDERID: "01", SALESORDERITEM: "02" });
myItem.BILLINGSTATUS = "P";
myItem.$save();