Versions Compared

Old Version 9

changes.mady.by.user James Forsyth

Saved on

compared with

New Version Current

changes.mady.by.user Keong Lim

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

This page will serve as a reference for how to use the A&AI DSL API and commonly used DSL queries.

Before You Start!

It's important that you engage the AAI team before running any adhoc DSL queries. The current process is to have the AAI team vet the DSL queries to make sure the traversal used is optimal and does not cause performance issues in A&AI. As edge rules and schema may change, it is important for clients to communicate the DSL queries that they use. It's important that, at the very least, we know who is using which queries so we can be cautious of changes in the future. And we can help you find the best way to get the data you need.


Table of Contents


Getting Started with the DSL API

To execute a DSL query, a client will perform a PUT on the dsl endpoint and include a payload that includes the dsl query to be run. The version dictates which release's REST API version the output will be based on.An AID for these custom queries is available on our AID page.


PUT /aai/v$/dsl?format={format}

...

Expand


{
  "results": [
    {
      "complex": {
        "physical-location-id": "complex5349-06",
        "complex-name": "complexsa-test",
        "resource-version": "1485403105490",
        "physical-location-type": "Example Location",
        "street1": "123 Example Street",
        "city": "Example",
        "state": "NJ",
        "postal-code": "12345",
        "country": "USA",
        "region": "USA",
        "latitude": "30.395968",
        "longitude": "-84.135344",
        "relationship-list": {
          "relationship": [
            {
              "related-to": "pserver",
              "related-link": "https://aai.onap:8443/aai/v16/cloud-infrastructure/pservers/pserver/pserver5349-06",
              "relationship-data": [
                {
                  "relationship-key": "pserver.hostname",
                  "relationship-value": "pserver5349-06"
                }
              ],
              "related-to-property": [
                {
                  "property-key": "pserver.pserver-name2"
                }
              ]
            }
          ]
        }
      }
    },...]
 
}


...

Expand


 {
    "results": [
        {
            "url": "https://aai.onap:8443/aai/v16/cloud-infrastructure/complexes/complex/EXAMPLEEXAMPLE_COMPLEX_ID",
            "complex": {
                "physical-location-id": "EXAMPLE_COMPLEX_ID",
                "complex-name": "Example",
                "resource-version": "1486837035912",
                "physical-location-type": "",
                "street1": "123 Mule St",
                "city": "MOSCOW",
                "state": "RU",
                "postal-code": "0",
                "country": "RUS",
                "region": "EMEA"
            }
        },...]
}


...

Expand


{
    "results": [
        {
            "id": "739696712",
            "node-type": "generic-vnf",
            "url": "https://aai.onap:8443/aai/v16/network/generic-vnfs/generic-vnf/85f60b5e-6eff-49c8-9a79-550ee9eb4806",
            "properties": {
                "vnf-type": "WX",
                "service-id": "d7bb0a21-66f2-4e6d-87d9-9ef3ced63ae4",
                "equipment-role": "UCPE",
                "orchestration-status": "created",
                "management-option": "ONAP",
                "ipv4-oam-address": "10.12.14.16",
                "ipv4-loopback0-address": "18.20.22.24",
                "nm-lan-v6-address": "2001:1890:e00e:fffe::1:2806",
                "management-v6-address": "2001:1890:e00e:fffd::773",
                "vcpu": 4,
                "vmemory": 8,
                "vmemory-units": "GB",
                "vdisk": 150,
                "vdisk-units": "GB",
                "in-maint": false,
                "is-closed-loop-disabled": false,
                "resource-version": "1499958805125",
                "vnf-id": "85f60b5e-6eff-49c8-9a79-550ee9eb4806",
                "vnf-name": "VNF_NAME"
            },
            "related-to": [
                {
                    "id": "739700808",
                    "node-type": "license",
                    "url": "https://aai.onap:8443/aai/v16/network/generic-vnfs/generic-vnf/85f60b5e-6eff-49c8-9a79-550ee9eb4806/licenses/license/EXAMPLEEXAMPLE_LICENSE"
                },
                {
                    "id": "411750576",
                    "node-type": "service-instance",
                    "url": "https://aai.onap:8443/aai/v16/business/customers/customer/EXAMPLE_CUSTOMER/service-subscriptions/service-subscription/EXAMPLE_SERVICE_SUBSCRIPTION/service-instances/service-instance/EXAMPLEEXAMPLE_SERVICE_INSTANCE"
                },
                {
                    "id": "15372328",
                    "node-type": "vnf-image",
                    "url": "https://aai.onap:8443/aai/v16/service-design-and-creation/vnf-images/vnf-image/78252548-efb6-4b42-9cf7-2b3900c5e7e2"
                },
                {
                    "id": "700920024",
                    "node-type": "vserver",
                    "url": "https://aai.onap:8443/aai/v16/cloud-infrastructure/cloud-regions/cloud-region/Cloudy/McCloudface/tenants/tenant/EXAMPLE_TENANT/vservers/vserver/EXAMPLE_VSERVER"
                }
            ]
        }
    ]
}


...

Expand
Walking back through relationships in the simple format:

Let's say you got back a large tree of output in the simple format and need to go through the list of objects to understand their relationships. For example, the output returned vnfs, vservers, pservers and complexes but you want to only look at the results of a particular complex. First, we'll find the JSON object for the complex by looking at the result objects for one with "node-type": "complex" and "physical-location-id": (the CLLI of the location you want to filter on) within the "properties" object. Next you would check the "related-to" object array for objects with "node-type": "pserver", take the "id"s and search for objects with those IDs in the results object array. You can keep crawling through the results in this way until you reach the objects you need. You can use this method for any property you want to filter on.

{
    "results": [
        ...,
        {
            "id": "14147624",
            "node-type": "complex",
            "url": "https://aai.onap:8443/aai/v16/cloud-infrastructure/complexes/complex/EXAMPLEEXAMPLE_COMPLEX_ID",
            "properties": {
                ...
                "physical-location-id": "EXAMPLE_COMPLEX_ID",
                ...
            },
            "related-to": [
                {
                    "id": "2134056",
                    "node-type": "pserver",
                    "url": "https://aai.onap:8443/aai/v16/cloud-infrastructure/pservers/pserver/EXAMPLE_PSERVER"
                },
                {
                    "id": "2158632",
                    "node-type": "pserver",
                    "url": "https://aai.onap:8443/aai/v16/cloud-infrastructure/pservers/pserver/EXAMPLE_PSERVER2"
                },...
            ]
        },...
    ]
}


...

Symbol

Examples

Description

[][node1, node2]Used for creating a union between nodes.
()

node('property','filter')

node(> node-filter)

Used for filtering the current node. Can be used with properties or filtering by related nodes, and multiple filters can be applied at once.
*

node*

node*('property','filter')

Used to return the current node, assuming it meets any filters.
>node1 > node2Used to traverse between nodes

...

  1. Start Node in the DSL Query should include filtered properties that are keys or indexed properties. These come from a special property in oxm (DslStartNodeProperties). The below will error out
    1. cloud-region*
    2. pserver('prov-status','PROV')
    3. ERR.5.4.6149 : DSL Error  while processing the query :Non indexed keys sent. Valid keys for cloud-region cloud-owner,cloud-region-id,cloud-type
  2. There should be atleast one return node type specified. If the user does not specify a "*" or store('x') on any node type it errors out
    1. generic-vnf('vnf-type','SW')('equipment-role','UCPE') > service-instance > service-subscription
    2. ERR.5.4.6152: No nodes marked for output
  3. Check if a valid edge exists between the node types specified and labels
    1. ERR.5.4.6107: No EdgeRule found for passed nodeTypes: cloud-region, l-interface
    2. ERR.5.4.6107: No rules found for EdgeRuleQuery with filter params node type: cloud-region, node type: complex, label: org.onap.relationships.inventory.Belongs, type: TREE, isPrivate: false
  4. Check for redundant edges to prevent the possibility of loops to occur from a DSL query.
    A > B, B > C, C > A
    1. ERR.5.4.6151: Validation error :Loop Validation failed
  5. Check if the dsl has a max type of vertices returned or traversed - if beyond that then the client should use CQ
    1. ERR.5.4.6151: Validation error :NodeCount Validation failed"
  6. Syntax Errors are caught at the grammar level
    1. ERR.5.4.6153: DSL Syntax Error while processing the query 
  7. Lower Timeouts for DSL Queries
    1. DSL Queries have a lower timeout than custom queries or any other APIs in resources or traversal to prevent the client from running adhoc queries
  8. aa


Best Practices

  1. Verify if the DSL traversal is optimal. Run .profile() on the underlying gremlin query
  2. If available always use keys or unique indexes in the start node or any node in the query
  3. Frequently used DSL queries should be encouraged to be converted to custom-queries since the start-node in a custom query has a URI
  4. Run the format=count and verify if the traversal can be reversed to get the optimal query

...

NODE('key1','value1') > [ NODE2*(>NODE3('key3','value3')), NODE3*]
 
{
    "dsl":"customer> service-subscription('service-type','example-service-type') > [ service-instance(> generic-vnf*('vnf-type','example-vnf-type')('model-version-id-local','1.0') ) , tennanttenant*]"
}
 
Give me service-instances and tenant related to the given service-subscription

...