Hiperspace 2.6.5

• .NETStandard 2.0

  • Microsoft.Bcl.HashCode (>= 6.0.0)

• net10.0

  • Microsoft.Bcl.HashCode (>= 6.0.0)
  • protobuf-net.Core (>= 3.2.56)
  • System.Numerics.Tensors (>= 10.0.10)

• net8.0

  • Microsoft.Bcl.HashCode (>= 6.0.0)
  • protobuf-net.Core (>= 3.2.56)
  • System.Numerics.Tensors (>= 10.0.10)

• net9.0

  • Microsoft.Bcl.HashCode (>= 6.0.0)
  • protobuf-net.Core (>= 3.2.56)
  • System.Numerics.Tensors (>= 10.0.10)

https://www.cepheis.com/hiperspace/20260802
# Overview
This release enhances the support for alternate indexes to include nested values and handling of unique references to other entities.

This enhancement removes the need to define additional element values to support view access.

---

## Alternate Index
The normal/**best** way to define an index is to include an access path.  The following *model* defines a Customer and Account ***and*** implicitly an alternate index for navigation from Customer to all accounts.
```
entity Customer (Id : Int32){Name : String}[Accounts : Account (Customer = this)];
entity Account (Id : Int32){Customer : Customer};
```
The `@AlternateIndex` property of a *key*/*value* allows for indexes to be created where it is not possible to define an access path (e.g. to `segment` or `aspect` that may have multiple implementations.  If Account is instead defined as a *segment*, it would not be possible to define an access path from `Book` to `Account` since the segment could be defined for any number of *elements*.
```
entity Customer = Node ()(Id : Int32) {Name : String} [Accounts : Account, TypeName = "Customer"];
segment Account = Node(), Edge() (Id : Int32) {Name : String, @AlternateIndex Book : Book} [TypeName = "Account", From = Book, To = this];
entity Book = Node() (Id : Int32) {Name : String}[TypeName = "Book"];
```
When `Book` is viewed as a *graph* `Node`, it has a `Froms` collection of `Edge` that includes all *Accounts* that refer to the `Book`.  `@AlternateIndex` creates an access path to `Account` from `Book`.

### ISO20022

[ISO20022.Static.BranchAndFinancialInstitution](https://github.com/channell/Hiperspace.ISO20022/blob/291d6bb1f03bc6925d31b702ccc53986a4217903/Static.hilang#L498) includes a nested value `ISO20022.Static.FinancialInstitution` that could be a *Bank*, a *LegalEntity* or both.
```
entity ISO20022.Static.BranchAndFinancialInstitution
   = Node (Name = FinInstnId.Nm, SKey = SKey, TypeName = "ISO20022.BranchAndFinancialInstitution")
   , ISO20022.Edges
       ( From = this
       , To = Bank
       , Name = BankName
       , FromTypeName = "BranchAndFinancialInstitution-Bank"
       , ToTypeName =  "Bank-BranchAndFinancialInstitution"
       )
(
   @XmlElement BrnchId            : ISO20022.Static.BranchData,
   @XmlElement FinInstnId         : ISO20022.Static.FinancialInstitution,
)
[
   @XmlIgnore, JsonIgnore
   Bank                           : ISO20022.Static.Bank (AnyBIC = FinInstnId.BICFI),
]  
```
This release adds the option to include `@AlternateIndex` for `ISO20022.Static.FinancialInstitution.BICFI` and have an index on every *entity/segment/aspect* that includes the `FinancialInstitution` reference.  When `ISO20022.Static.Bank` is viewed as a graph `Node` it will include a *edges* to and from every `BranchAndFinancialInstitution` that referenes it.

---

## Unique Reference
When an *element* has an extent reference to another *element* it is normally a **set**, in the top example `Customer.Accounts` is a set because any number of `Account` could refer to `Customer`, but if the parameter to the reference is the same as key of the referenced *element* it is included as **single** since it will never have more than one value. When an *element* includes a reference to an `aspect` (single value inheriting the owner’s key) the **single** value behaves like a nested value:
* Reading the `Value` does a lazy lookup from the `SubSpace` cache, or from the underlying `HiperSpace`
* Setting the `Value` copies the *owner* key to the aspect transparently to behave like a value but stored seperately.

This release add the ability set foreign references in the same way as `aspect`, but instead of binding the *owner* of the aspect, the parameter fields in the referencing element are updated.

For the ISO20022 example above the code `var aBranch = new BranchAndFinancialInstitution { Bank = goldmanSachs };` will assign `goldmanSachs.AnyBIC` value to `aBranch.FinInstnId.BICFI` since that is semantically equvilent to `var aBranch = new BranchAndFinancialInstitution { FinInstnId = new ISO20022.Static.FinancialInstitution { BICFI = goldmanSachs }};`

---
# Worked Example
The [ISO20022](https://github.com/channell/Hiperspace.ISO20022/blob/main/Static.hilang) includes the defintion of **Party** that can *optionally* reference *a Legal Entity*, *a Bank* or *both*, in addtion to generic *person* nand *branch* information.  The entity can be *viewed* as a `Node` in graph (*with the `TypeName` "ISO20022.Party"*) **and** up to four `Edge`:
* **Party-Bank** (*if `OrgId.AnyBIC` has a value*) - via Party Key
* **Bank-Party** (*if `OrgId.AnyBIC` has a value*) - via Party AnyBIC index
* **Party-LegalEntity** (*if `OrgId.LEI` has a value*) - via Party Key
* **LegalEntity-Party** (*if `OrgId.LEI` has a value*) - via Party LEI index

if we query `SELECT node, edge.To AS Party FROM Nodes AS node, n.Tos /*implicit join*/ AS edge WHERE node.Name = 'Goldman Sachs' AND edge.TypeName = 'Bank-Party';` will return a result set of all *parties* that participate in an ISO20022 message for the Bank with the name Goldman Sachs. The query plan will perform:

1. Create a template `Node` with `Name` "Goldman Sachs"
2. Query  `SetSpace<Node>` for all `Node` that has a index on Name (*including `node.TypeName = 'ISO20022.Bank'` would limit the query to `SetSpace<Bank>`*)
3. Create a template `Bank` with  `Name` "Goldman Sachs"
4. Query `SetSpace<Bank>` using the Bank Name index
3. Create a template `Edge` with `From` set to the `Node` object for "Goldman Sachs" and TypeName 'Bank-Party'
4. Query `SetSpace<edge>` (*since edge TypeName is set, only `SetSpace<Party>` is searched*)
5. Create a template `Party` with `Bank` set to "Goldman Sachs" (*the `binder` code adds an `OrgId` value, and set `OrgId.AnyBIC` to `Bank.AnyBIC`*)
6. Query `SetSpace<Party>` using the Party AnyBIC index
7. Project a data frame of Node and Party

The following LINQ query will traverse the graph of nodes through all edges (upto a length 100) to find CreditTransferTransaction associated with "Goldman Sachs":
```
from node in space.Nodes
where node.Name == "Goldman Sachs"
let transfer = node.HiperEdges("*", 100, new HashSet<string> {"Fact:ISO20022.Cube.CreditTransferTransaction"}
select transfer;
```
For **Hiperspace.DB** the graph search will use GPU parallel search, otherwise a parallel pipeline is used.

---

## Referenced libraries
External references have been updated to the latest version