Entity Search

Entities can be discovered via their searchable fields.

Searchable Fields

Factern indexes the data of an information node if the field type of that information node is searchable.

For example, here we create a searchable field.

POST /createfield
{
    "parentId": "00000000C320A7BFD903745851915F6C33D20634E36C37C6",
    "name": "FullName",
    "searchable": true
}

We can add the field to any entity to make the entity searchable by that field.

For example, the following entity becomes searchable using the field FullName via the value "John Watson".

POST /write
{
    "nodeId": "00000000404AE4402DF969ACE2C2DA9133A23EA48773AF8A",
    "document": {
        "FullName": "John Watson",
        "FullAddress": "221b Baker Street, London, UK"
    }
}

Note that an entity can be searchable by any number of fields.

Entities can even be searchable by a field of field (recursively).

For example, if City is a searchable field type, then the following makes the entity 00000000404AE4402DF969ACE2C2DA9133A23EA48773AF8A searchable using the value "London".

POST /write
{
    "nodeId": "00000000404AE4402DF969ACE2C2DA9133A23EA48773AF8A",
    "document": {
        "FullName": "John Watson",
        "Address": {
            "Street": "221b Baker Street",
            "City": "London",
            "Country": "UK"
        }
    }
}

Searching

The searchentity API allows explicit searching of entities by field values.

For example, in the following we search for entities having a field type of City having value "London".

POST /searchentity
{
    "fieldId": "frn:field::City",
    "operator": "equals",
    "term": "London"
}

The response indicates we found two entities.

Response:
{
    "nodes": [
        {
            ...
            "factType": "Entity",
            "nodeId": "000000004EB2A369CBDD918BE61396563EED662825569979"
        },
        {
            ...
            "factType": "Entity",
            "nodeId": "000000001C49F25DC1D908FC1B52A554E8FB5D6F690AC12C"
        }
    ]
}

Operators

Supported searchentity operators:

Operator Matches Fields
equals Exactly equal to the term
startsWith Starting with the term
contains Containing the term

The Entity Query Syntax

The functionality of the searchentity can be used implicitly in other API calls using the Entity Query syntax:

    "[" =[,...] "]"

Entity queries can be using anywhere the nodeId of an entity can be used.

For example, in the following, FullName is a searchable field:

POST /write
{
    "nodeId": "00000000404AE4402DF969ACE2C2DA9133A23EA48773AF8A",
    "document": {
        "FullName": "John Watson"
    }
}

Subsequent additional fields could be added referring to the entity using an entity query rather than the explicit nodeId.

POST /write
{
    "nodeId": "[FullName=John Watson]",
    "document": {
        "Address": {
            "Street": "221b Baker Street",
            "City": "London",
            "Country": "UK"
        }
    }
}

Note that if more than one entity satisfies a given Entity Query then it is considered to be a client request error.

Multiple Queries

Multiple queries can be specified in the same entity query, if necessary.

Continuing the previous example, the nodeId could have been specified using the Address parts of the data.

POST /write
{
    "nodeId": "[Street=221b Baker Street,City=London]",
    "document": {
        "FavouriteColour": "Red"
    }
}

Escape Characters

Entity Queries where the term includes embedded commas need to be escaped using the backslash character. Of course, that means backslashes, too, need to be escaped.

For example, if the data for the entity was written as

POST /write
{
    "nodeId": "00000000404AE4402DF969ACE2C2DA9133A23EA48773AF8A",
    "document": {
        "FullAddress": "221b Baker Street, London, UK",
        "FullName": "John\\Watson"
    }
}

the entity

[FullAddress=221b Baker St.\, London\, UK,FullName=John\\Watson]
POST /write
{
    "nodeId": "[FullAddress=221b Baker St.\\, London\\, UK,FullName=John\\\\Watson]",
    "document": {
        "FavouriteColour": "Red"
    }
}