Search for Twins

Find your own and others' Digital Twins by using both Search _and _Advanced Search functions.

This page covers:

• Comparison Table - Search vs Advanced Search
• Search for Twins
• Using the Search function
• Advanced Search for Twins
• Using the Advanced Search function

You can find your own and others’ Digital Twins using the Search _and _Advanced Search functions. Although you can use the same search criteria, they have important differences - please see our Comparison Table for details.

Comparison Table - Search vs Advanced Search

Search for Twins

Use the Search Twin call to find your and others' Digital Twins in your IOTICS ecosystem. You can select and combine one or more search criteria, including:

• Property: define a list of Twins properties, such as Type, Label, Comment, Last Update, etc. Properties can be matched using equals.
• Location: define Latitude, Longitude and Radius expressed in Km. You can search for one location at a time.
• Text: define one or more keywords that must match text fields from Twin’s Label and Comment.
• Scope (ownership): distinguish between finding only your own local Digital Twins, vs all _global _Digital Twins.

Using the Search function

Click here to see the prerequisites.

import json
from datetime import datetime, timedelta, timezone
from requests import request

# Search headers require a new header "Iotics-RequestTimeout".
# The latter is used to stop the request once the timeout is reached
search_headers = {
    "accept": "application/json",
    "Iotics-ClientAppId": "example_code",
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
    "Iotics-RequestTimeout": (
        datetime.now(tz=timezone.utc) + timedelta(seconds=5)
    ).isoformat(),
}

# The variable below will include the list of Twins found
twins_list = []

with request(
    method="POST",
    url=f"{HOST}/qapi/searches",
    headers=search_headers,
    stream=True,
    verify=True,
    params={"scope": "LOCAL"},
    json={
        "responseType": "FULL",
        "filter": {
            "properties": [
                {
                    "key": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
                    "uriValue": {"value": "http://data.iotics.com/app#Model"},
                }
            ],
            "text": "temperature",
            "location": {
                "location": {"lon": 52.2, "lat": 0.119},
                "radiusKm": 3.2,
            },
        },
    },
) as resp:
    resp.raise_for_status()
    # Iterates over the response data, one Host at a time
    for chunk in resp.iter_lines():
        response = json.loads(chunk)
        twins_found = []
        try:
            twins_found = response["result"]["payload"]["twins"]
        except KeyError:
            continue
        finally:
            if twins_found:
                # Append the twins found to the list of twins
                twins_list.extend(twins_found)

print(f"Found {len(twins_list)} twin(s)")

Advanced Search for Twins

Use the Advanced Search Twin call to find your and others' Digital Twins in your IOTICS ecosystem. You can select and combine one or more search criteria, including:

• Property: define a list of Twins’, Feeds’ and Inputs’ properties, such as Type, Color, and Last Update. Properties can be combined using operators (i.e. ">", "<=", "!", etc.)
• Location: define Latitude, Longitude and Radius expressed in Km. You can search for multiple locations simultaneously.
• Text: exact match of any text-value property on a Twin, Feed or Input.
• Scope (ownership): distinguish between finding only your own local Digital Twins, vs all global Digital Twins.

Using the Advanced Search function

Click here to see the prerequisites.

Let's find the Twins which:

• Have been created before 10/02/2022 AND
• Don’t have myOnto:someProp with value 20 (but do have it set!) OR
• Have a feed with myOnto:anotherProp set to False

{
  "prefixes": {
    "myOnto": "http://example.org/my/ontology/",
    "iotics": "http://data.iotics.com/iotics#"
  },
  "filter": {
    "and": [
      {"<": ["iotics:createdAt", {"strdt": ["2022-10-02", "xsd:date"]}]},
      {"or": [
        {"!=": ["myOnto:someProp", 20]},
        {"==": [["$feed", "myOnto:anotherProp"], false]}
      ]}
    ]
  }
}

🚧

Distinguish between your own local _Digital Twins and others' _remote Digital Twins

• Local: returns all Digital Twins in your own IOTICSpace
• Global: returns all Digital Twins in others' (remote) IOTICSpaces.

Please note that you will only find Digital Twins that you have permission to find. See Selective Sharing for Metadata and Data for more information on access permissions.

The following table provides an indication of the filters that can be used in the request parameters when searching for Twins.

An important feature of both searching functions is that it allows you to describe one or more Twins through the responseType body parameter. It can be set to:

• MINIMAL: used to return minimal responses including a Twin's DID.
• LOCATED: includes the MINIMAL fields in addition to the Twin's location;
• FULL (default): provides a complete description of the Twin, including all metadata about the Twin, its Feeds, Inputs and the Feeds' and Inputs’ Values.