Azure-docs: Advance spaces query

[obrookstein]

Hi,

Is there a way to get all spaces that apply to a more specific / advanced filter? Specifically I'd like to get all children spaces of a specific space, that applies to more than one propertyKey value (i.t. propertyKey1=x, and propertyKey2=y), and for integer be able to compare (propertyKey3>5). Is it possible to do so in one API call?

Thanks,

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 15e6c9b8-3a4a-7bd0-408c-84e17cd43f8b
• Version Independent ID: 78cd1ec1-1150-724c-af4a-cd75debefd12
• Content: Azure Digital Twins common query patterns
• Content Source: articles/digital-twins/how-to-query-common-apis.md
• Service: digital-twins
• GitHub Login: @KingdomOfEnds
• Microsoft Alias: v-adgera

[KrishnaG-MSFT]

@obrookstein Thanks for your comment. We are actively investigating and will get back to you shortly.

[AshokPeddakotla-MSFT]

Adding author @KingdomOfEnds for further help. Adam, please check and provide your suggestions.

[KingdomOfEnds]

Hi @obrookstein - Great question! It is possible to do all of the following in a single API query:

1. Call back all child nodes of parent space.
2. Call back all child nodes exhibiting two specific properties (having those properties and specific values for them).
3. Call back all child nodes exhibiting a specific property below a threshold.

Starting with the following Spaces:

    [
        {
            "id": "ad604988-5297-4c24-a14d-2fb8fdb73fc3",
            "name": "Floor 1",
            "typeId": 14,
            "parentSpaceId": "f026414e-b4b2-4346-9819-fa5e81f2c598",
            "subtypeId": 13,
            "statusId": 12
        },
        {
            "id": "597271f1-031a-4e3f-ba58-5da7ce339ed6",
            "name": "Area A",
            "typeId": 14,
            "parentSpaceId": "ad604988-5297-4c24-a14d-2fb8fdb73fc3",
            "subtypeId": 13,
            "statusId": 12
        },
        {
            "id": "2a39e652-5835-46c4-8a6e-68002743a1f3",
            "name": "Conference Room 11",
            "typeId": 14,
            "parentSpaceId": "ad604988-5297-4c24-a14d-2fb8fdb73fc3",
            "subtypeId": 13,
            "statusId": 12
        },
        {
            "id": "9d835f45-9a33-49ca-84cb-ac5c8bea809e",
            "name": "Focus Room A1",
            "typeId": 14,
            "parentSpaceId": "ad604988-5297-4c24-a14d-2fb8fdb73fc3",
            "subtypeId": 13,
            "statusId": 12
        },
        {
            "id": "f026414e-b4b2-4346-9819-fa5e81f2c598",
            "name": "Quickstart Building",
            "typeId": 14,
            "subtypeId": 13,
            "statusId": 12
        }
    ]

• To bring back all descendants: ?spaceId=ad604988-5297-4c24-a14d-2fb8fdb73fc3&traverse=Down.
• &$filter=TypeId eq 14&$filter=SubtypeId eq 13 requires two values for two specific properties.
• &$filter=StatusId le 12 does a comparison for some value.

All can be combined like so:

 https://<<YOUR_URL>>.azuresmartspaces.net/management/api/v1.0/spaces?spaceId=ad604988-5297-4c24-a14d-2fb8fdb73fc3&traverse=Down&$filter=TypeId eq 14&$filter=SubtypeId eq 13&$filter=StatusId le 12

[
    {
        "id": "ad604988-5297-4c24-a14d-2fb8fdb73fc3",
        "name": "Floor 1",
        "typeId": 14,
        "parentSpaceId": "f026414e-b4b2-4346-9819-fa5e81f2c598",
        "subtypeId": 13,
        "statusId": 12
    },
    {
        "id": "597271f1-031a-4e3f-ba58-5da7ce339ed6",
        "name": "Area A",
        "typeId": 14,
        "parentSpaceId": "ad604988-5297-4c24-a14d-2fb8fdb73fc3",
        "subtypeId": 13,
        "statusId": 12
    },
    {
        "id": "2a39e652-5835-46c4-8a6e-68002743a1f3",
        "name": "Conference Room 11",
        "typeId": 14,
        "parentSpaceId": "ad604988-5297-4c24-a14d-2fb8fdb73fc3",
        "subtypeId": 13,
        "statusId": 12
    },
    {
        "id": "9d835f45-9a33-49ca-84cb-ac5c8bea809e",
        "name": "Focus Room A1",
        "typeId": 14,
        "parentSpaceId": "ad604988-5297-4c24-a14d-2fb8fdb73fc3",
        "subtypeId": 13,
        "statusId": 12
    }
]

This example's a bit limited since Spaces, by their OData definitions, only have a few pre-defined attributes. However, it is quite possible to extend this approach to custom attributes. The trick here is that multiple $filters can be appended to the core query.

Please let me know if I've satisfactorily answered your question. Thanks!

[obrookstein]

Hey @KingdomOfEnds,

Thanks for the detailed answer - that's exactly what I was looking for. Only tow things I'm missing are -

1. Does this work for Custom PropertyKeys using the exact same syntax? i.e. "&$filter=propertyKeyName eq value"?
2. Where can I find documentation with all operators? not-equal, larger than etc.

Thanks,

[KingdomOfEnds]

@obrookstein - Glad to help. Ah, let' see:

1. I think this is one of the most helpful documents to see a list of all supported syntax operators. While it applies to Azure Search, it provides a complete list of all OData comparison operators that are available. Those operators can be used in any DT queries as well.
2. Yep! You can concatenate specific property keys and values propertyKey=AreaInSqMeters&propertyValue=30 in the same way as filters above. Slightly different syntax (my apologies there) but the overall query should look fairly similar. You can substitute in the propertyKey clauses for the filter clauses.

[obrookstein]

Thanks,

Yes - I also found that the graph api uses the same syntax.

So, if the syntax for propertyKeys is different, can I do that -
PropertyKey=AreaInSqMeters&propertyValue=30&PropertyKey=Temperature&propertyValue=25?

Does the API takes into consideration the order of the parameters and “bind” the value to the right property? usually the order of the parameters doesn’t affect the call. Also, using this syntax how do I use other operators than just ‘=‘?

[KingdomOfEnds]

That's my mistake. For any customized properties, you must use Extended Property Keys (which do not attach to the underlying OData schema) - for other "property or attribute-like" entities (ADT supports Types, Properties, and OData attributes) some additional filtering options are available (attributes attached directly to the OData schema for example).

(Extended) Property Keys are created in two ways:

1. Through the API of the entity you want to create them for (e.g. - /api/v1.0/spaces/{{ID}}/properties).
2. Through the PropertyKey API (/api/v1.0/propertykeys/) itself.

To assign a value to your Property Keys, you'd want to use PUT /api/v1.0/spaces/{{ID}}/properties or POST to create one from scratch.

However, I'm getting an error when Creating or Updating a PropertyKey. I unfortunately do not maintain the Swagger document nor the API itself (I just returned to the Digital Twins team).

To spec, you should be able to query:

 https://<<YOUR_URL>>.azuresmartspaces.net/management/api/v1.0/spaces?spaceId=ad604988-5297-4c24-a14d-2fb8fdb73fc3&traverse=Down&propertyKey=propKey1&propertyValue=propValue1&propertyKey=propKey2&propertyValue=propValue2

I don't believe filtering using comparison operators is possible through Extended Property Keys alone (however you may query to return a value and execute a second call based on the result).

[KingdomOfEnds]

I've also reached out to the engineering team to provide some clarification about filtering, ordering, and status of the Swagger document.

[lyrana]

Hi @obrookstein unfortunately what you're trying to achieve isn't currently supported in one single API call, but you are able to retrieve up to 1000 space nodes with properties and do the property value filtering client side. On your Management API swagger page you'll find a section on OData. You can also view the sample swagger here. What you're aiming for in terms of $filter=properties/any(c: c/ ge '') is not supported, but you can at present retrieve all child spaces including their properties with spaces/?includes=childspacesproperties,childspaces
On the swagger page if you select a request and click "Try it out" you'll be able to view all of the possible includes values for that request.

[obrookstein]

@KingdomOfEnds , @lyrana ,
Thank you both for the detailed answers. I'll do the filtering on the client side as suggested, after polling all child spaces, and their properties.

Thanks!

[AshokPeddakotla-MSFT]

@obrookstein We will now proceed to close this thread. If there are further questions regarding this matter, please tag me in your reply. We will gladly continue the discussion and we will reopen the issue.