Namespace: xsds

xsds

XS Data Services (XSDS) enable the seamless consumption of HANA database artifacts in XS-based applications. The XSDS API provides a high-level abstraction of the database API ($.db, $.hdb) and gives access to HANA artifacts such as CDS entities or stored procedures.

Classes

Entity
Expr
Query
Rename
Transaction

Methods

<static> $defineEntity(entityName, tableName, fields, options) → {sap.hana.xs.libs.dbutils.xsds.Entity}

Defines new entity based on a plain HANA table.

Returns the constructor for new entity instances. For details on the field mapping, see {sap.hana.xs.libs.dbutils.xsds.$importEntity}.

Many-to-many associations

Defining many-to-many associations with $defineEntity differs slightly from $importEntity in that links between source and target instances are represented by table records instead of entities. The association specification thus looks like:


field: {
  $association: {
    $entity: entity,
    $viaTable: table,
    $source: { foreign-key-spec },
    $target: { foreign-key-spec }
  }
}

foreign-key-spec defines the foreign key relationship between the linking table and the source and target tables, respectively. Please refer to the section on one-to-one associations in sap.hana.xs.libs.dbutils.xsds.$importEntity) for details.

Parameters:
Name Type Argument Description
entityName string Name of the entity to define.
tableName string Fully qualified name of table to import, including schema.
fields object <optional>
 Field mapping overrides for column names, keys, and associations.
options object <optional>
 The definition options.
Properties
Name Type Argument Description
$ignoreColumns string[] <optional>
 List of table columns not to import (deprecated).
$renameColumns function <optional>
 A function to map column to field names.
$unmanaged boolean <optional>
 Import entity, but do not manage entity instances.
Returns:
A constructor for the new entity instance.
Type
sap.hana.xs.libs.dbutils.xsds.Entity
Example
var Address = XSDS.$defineEntity("EPM.Address", "\"SAP_HANA_DEMO\"." +
                "\"sap.hana.democontent.epm.data::EPM.MasterData.BusinessPartner\"", {
    address: {
        $association: {
            $entity: "\"SAP_HANA_DEMO\".\"sap.hana.democontent.epm.data::EPM.MasterData.Addresses\"",
        },
        addressid: {
            $column: "ADDRESSID"
        }
    }
}, { $renameColumns: XSDS.Rename.$lowercase });

<static> $getEntity(name) → {object}

Retrieves constructor function of previously defined entity.

Entities must be imported exactly once. Attempting to re-import an entity (using the same entity name) throws an exception in order to avoid conflicting imports. The $getEntity function is used to refer to an entity import from an external file.

Parameters:
Name Type Description
name string The name of the entity.
Returns:
Entity constructor or null if there is no entity with given name.
Type
object
Example
// file sample_base.xsjslib
var MyEntity = $importEntity("namespace", "entity");

// file sample_util.xsjslib
var base = $.import("./sample_base.xsjslib");
var MyEntity = XSDS.$getEntity("namespace::entity");

<static> $importEntity(cdsNamespace, cdsName, fields, options) → {sap.hana.xs.libs.dbutils.xsds.Entity}

Imports a CDS entity as XSDS entity. Returns constructor function creating new entity instances and manipulating existing instances.
Field Mapping

Imports may change field properties or add additional fields. This feature is used to override key definitions and to define additional associations not explicitly expressed by the data model.

$key (boolean or string): set or unset key property for field. If set to the name of a HANA sequence then that sequence is used to generate new key values for new entity instances. Optional.

$init (value or function): initial value for new instances. Value to assign to fields in newly created instances. If $init is a function, the function is passed the instance object being built, after all non-functional $init values have been assigned. May also be used for key fields, analoguous to $key. Optional.

$lazy (boolean): true if the associated entity or entities should be retrieved lazily. Optional. Defaults to false.

$cascadeDiscard (boolean): true if discarding the parent entity should also discard the associated entity or entities. Optional. Defaults to false.

Associations

XSDS supports one-to-one associations by foreign key, one-to-many associations by backlinks, many-to-many associations by entities, and unmanaged associations. Existing CDS associations are imported automatically, but additional associations may be added during import.

One-to-one associations (foreign key)

A one-to-one association associates a (potentially optional) target entity instance with the source target instance.


field: {
  $association: { $entity: entity },
  key1: { $column: column1, [ $none: value1 ] },
  key2: { $column: column2, [ $none: value2 ] }, ...
}

entity refers to the associated entity type and may be the constructor function or the name of the entity.

keyX are the names of the fields of the target entity, and columnX are the names of the columns of the source entity. The foreign key does not have to match the primary key of the target entity.

An optional $none value specifies a dedicated value that denotes that no instance is currently associated with the parent instance. For CDS entities, $none defaults to undefined.

One-to-many association (backlinks)

A one-to-many association associates an arbitrary number of instances of the target entity to the source entity instance. The associated instances are stored in an array-like object in the source instance. Each target cannot be assigned to more than one instance.


field: {
  $association: {
    $entity: entity,
    $viaBacklink: field
  }
}

entity refers to the associated entity type and may be the constructor function or the name of the entity.

Many-to-many association (entities)

A many-to-many association associates an arbitrary number of instances of the target entity to the source entity instance. The associated instances are stored in an array-like object in the source instance. Each target may have an arbitrary number of sources. The actual links are stored in an external entity that has two one-to-one associations that will link source and target instances.


field: {
  $association: {
    $entity: entity,
    $viaEntity: entity,
    $source: field,
    $target: field
  }
}

entity refers to the associated entity and the linking entity, respectively, and may be the constructor functions or the names of the entities. $source and $target specify the field names of the associations in the linking entity that denote the source and the target entities of the link, respectively.

Unmanaged association (JOIN condition)

Unmanaged associations define their JOIN condition directly. Associated instances are stored in a read-only array-like object that bypasses the XSDS entity cache.


field: {
  $association: {
    $entity: entity,
    $on: join-cond
  }
}

join-cond is a string that defines the SQL ON-condition when joining source and target entity tables. Individual path components must be fully quoted, e.g., $SOURCE."x"."y"."z". The special variable $SOURCE refers to the source entity.

Parameters:
Name Type Argument Description
cdsNamespace string The context of the CDS entity to import.
cdsName string The name of the CDS entity to import.
fields object <optional>
 Additional field mappings, e.g., for associations.
options object <optional>
 The import options.
Properties
Name Type Argument Description
$entityName string <optional>
 Overrides the default entity name.
$schemaName string <optional>
 Sets the schema name.
$tableName string <optional>
 Forces an alternative table name.
$ignoreFields string[] <optional>
 A list of entity fields not to import (deprecated).
$renameFields function <optional>
 A function to map column names to field names.
Returns:
A constructor for the new entity instance.
Type
sap.hana.xs.libs.dbutils.xsds.Entity
Examples
// import CDS entity
var SoHeader = XSDS.$importEntity("sap.hana.democontent.epm.data", "EPM.SO.Header");
// override key settings on import
var SoHeader = XSDS.$importEntity("sap.hana.democontent.epm.data", "EPM.SO.Header", {
  SALESORDERID: { $key: false }, HISTORY: { $key: true }
});
// initialize fields automatically
var SoHeader = XSDS.$importEntity("sap.hana.democontent.epm.data", "EPM.SO.Header", {
  LIFECYCLESTATUS: { $init: "A" }
});
 
// add one-to-many association with backlinks
var SoHeader = XSDS.$importEntity("sap.hana.democontent.epm.data", "EPM.SO.Header", {
  items: {
    $association: {
      $entity: "sap.hana.democontent.epm.data::EPM.SO.Item",
      $viaBacklink: "SALESORDERITEM"
    }
  }
});
// unmanaged association
var MyOrder = XSDS.$importEntity("sap.hana.democontent.epm.data", "EPM.SO.Header", {
  mainItems: {
    $association: {
      $entity: "sap.hana.democontent.epm.data::EPM.SO.Item",
      $on: "$SOURCE.\"mainItems\".\"NETAMOUNT\" >= $SOURCE.\"NETAMOUNT\" / 3"
    }
  }
});