Named Query

NOTE –Named Queries are still supported (Dublin) but will be retired since we now have a tool to create custom queries on the fly.

But what if someone just wants to collect data from a piece of a model?  Or wants to pull data that is not defined as a model?    Or would like to pull data that’s related to a model, but does not want to see the entire topology in the result set?  

Since the model was complicated enough by itself, a second mechanism, the “Named Query” was built to support these kinds of requests.  

A Named Query is similar to an SDC-Model in that it defines a topology or subgraph; but unlike models, it is made up entirely of widget-level models and does not support the kinds of rules that models need to validate data.  

It is only focused on pulling data out of the database.  It does not use "service" or "resource" level models.


Algorithm at a high level

One common feature of both models and named-queries is that they both identify a single starting point in the graph where an “instance” of this model can be identified.  

From that single starting point, a topology (really a tree) is defined which defines what other data the model or named-query relates to in the database.   

Someone might have a model for a particular kind of logical link that should always connect an l-interface on a vserver of type X with an l-interface on either a vserver of type Y or Z.

The model would use the logical-link widget to start with and would have rules that limit the things being connected (X to Y, or X to Z).  

The model captures the rules so that when we need to use it to collect or verify data, we can traverse nodes starting at the initial starting point and always knowing where we are in the topology and what are all the allowable next-steps from that point.   


At present we only allow models or named-queries to be defined which match up with our existing database rules.  

For example, you cannot currently define a customer model where a customer node connects directly to a pserver.  There is no direct relationship in the database between those two node-types, so there would never be instance data found for this model or a way to put it into the database.  In theory, we could simply define a new allowed-edge (relationship) whenever a model definition is created.  That is a longer-term goal (maybe).  

But the database needs to make sense as a whole and not just record a jumble of contradictory visions of what our network looks like.  

While designers should be able to mix and match existing models to build new things, the introduction of new types of relationships will probably need to go through some sort of review board.  

For now widget types and properties and connection rules are pre-defined but can be used in many different combinations to define service and resource models.  Widget models are defined at the time the schema is defined since they currently track our schema 1 to 1.


Model Types

Model Type:  Widget Model

A widget-model is the lowest level type of model.  

It does not point to any other widget-models/resource-models or service-models.  

Is at the “leaf-level” of what SDC cares about.  

NOTE – The name of a widget model will be identical to the name of the AAI node type that it corresponds to.    


Model Type:  Resource Model  

A Resource Model captures levels of complexity by defining a topology of widget-models and/or other resource-models.  

Its first element must be a widget-type model which represents the starting point we would use when locating a single instance of this resource in the AAI database.


Model Type: Service Model 

A Service Model groups together other service-models, resource-models and/or widget-models to define a service.    

As with a resource-model, its first element must be a widget-type model which represents the starting point we would use when locating a single instance of this service in the AAI database.

Deprecating Named Queries in Dublin Release

AAI-1989 - Getting issue details... STATUS

ReferenceNamed Query Details

APPC-1245 - Getting issue details... STATUS

APPC is using AAI karaf bundle inherited from CCSDK. There is no one consolidated place to store all the aai query.



POLICY-1278 - Getting issue details... STATUS

See also Policy Named Query

VID-355 - Getting issue details... STATUS

  • getServiceModelsByServiceType – 6e806bc2-8f9b-4534-bb68-be91267ff6c8
  • component-list – 0367193e-c785-4d5f-9cb8-7bc89dc9ddb7

CCSDK-962 - Getting issue details... STATUS

  • No labels


  1. I'm trying to take advantage from Custom queries which I believe is replacement for Named queries.

    I followed docs on:

    Sadly, information about query payload is incomplete, I'm not sure what namespace in "start" key mean? I managed to make successful query with following body:

    { "start": [ "/nodes/pnfs" ] }

    I don't have idea why "nodes" part works?

    Currently I managed to run this example on K8s instance, same example on docker didn't succeed, I got 404 with "Node Not Found. Start URI returned no vertexes, please check the start URI". I'm running resources and traversal images. Is there additional image I missing?

    Of course PNF record is available under:


    1. Hi Krzysztof Kurczewski ,

      The "start" parameter can be either a single string or an array of strings. The contents of the "start" is basically any valid REST URL path for AAI-Resources. The "/nodes/" query is documented here:

      The effect of using the payload with "start" by itself is the same as doing a GET on each of those URLs and returning all the (de-duplicated) results in a single response.

      I have tested and confirmed that the Traversal custom query works with this payload:

       "start": [

      and gives these results as an example:

      curl --verbose --silent --insecure --user AAI:AAI --header 'Accept: application/json' --header 'X-TransactionId: testaai' --header 'Content-Type: application/json' --header 'X-FromAppId: AAI' --upload-file data-customquery.json 'https://${AAI_IP}:30233/aai/v14/query?format=count'
      > PUT /aai/v14/query?format=count
        "results": [
            "pnf": 1,
            "service-subscription": 41

      If you are still having problems making it work, perhaps you could join the AAI Developers Meeting to get more help.

    2. Also note that the default connection for AAI-Resources is "real-time" but the default connection for AAI-Traversal is "cached", so if you had just created the PNF and then immediately attempted to use the custom query to find it, then it's possible you did not see it due to the lag in updating the cache.

      If you add the HTTP header 'Real-Time: true' to your call, then AAI-Traversal will also use a "real-time" connection instead of the "cached" connection and you should see the results immediately.

      Otherwise, wait about 10 seconds and try again. If you see the results change, then you know it's due to the caching.

      See also AAI-2416 - Getting issue details... STATUS

    3. As discussed on 2019-05-30 AAI Developers Meeting the default "in-memory" database setup means the microservices are isolated from each other. Need to install a Cassandra instance that they can both use.