Performing Search

You can search for entities using the entity type and search criteria. You can define a search criteria using filter expressions based on entity properties as defined in the API reference. Search results return a paginated list of entity IDs that match the filter criteria.

Search Request

Format of the Search Request body:
{ "entity_type": "string", "filter": "string", "sort_by": { "field": "string", "order": "ASC" }, "size": 0, "cursor": "string", "time_range": { "start_time": 0, "end_time": 0 } }

Entity Type

In the Entity Type field, use the entity types defined in AllEntityType enum in the API Reference.

Filter Expression

A filter expression defines search criteria in one of the following formats:
  • {field_name}
    {binary operator}
    {field_value}
  • {field_name}
    {unary_operator}
Optionally, complex expressions can be designed using {logical operators} and parenthesis (...).
{field_name}
The name of a field in an Object. For example, VirtualMachine has a field named
vendor_id
.
{binary operator}
Used to compare a field to a value creating an expression.
{unary_operator}
Unary operator is used to test the field_name against the operator check. For example, IS SET is used to determine if a field is non NULL.
{field_value}
Represents the value of a field and can either be a number, string , list of numbers or list of strings.
{logical operator}
Logical operators are used to create complex filters.
For example:
(name = '
my_vm
') OR (vendor_id = '
vm-101
')
parentheses (...)
Parentheses are used to group expressions. They also determine the order in which the components of the expression are evaluated. For example:
((name = '
my_vm
') AND (default_gateway = '
10.1.1.1
'))

Considerations

  • You can use spaces in filter expressions.
  • Use quotes with strings. You need not use quotes with numbers.

Building Filter Expression

Components of a filter expression are:
FIELD_NAME
OPERATOR
VALUE
FIELD_NAME
Field name can be a property defined in the model object as per the API Reference or it can be a property of a related object in the response. For example, a subset of the VirtualMachine object properties appears as follows:
{ "entity_id": "18230:1:1158969162", "name": "NSX_Controller_9e80ec74-57ce-4671-8fd7-b5884a997535", "entity_type": "VirtualMachine", "ip_addresses": [ { "ip_address": "10.197.17.74", "netmask": "255.255.255.0", "network_address": "10.197.17.0/24" } ], "default_gateway": "10.197.17.1", "cluster": { "entity_id": "18230:66:1293137396", "entity_type": "Cluster" }, "host": { "entity_id": "18230:4:652218965", "entity_type": "Host" } }
From the preceding model, you can use the following field names:
  • Direct primitive properties
    • name
    • default_gateway
  • Properties inside the structure.
    For example:
    • ip_addresses.ip_address.
    • host.entity_id
  • Properties of a related object.
    For example:
    • host.name
    • cluster.name

Aggregation Search API

Aggregation Search Request
Format of the aggregation search request body :
{ "entity_type":"{ENTITY_TYPE}", "filter": "{FILTER}”, "aggregations": [ { "field": "{FIELD}", "aggregation_type": "{AGGREGATION_TYPE}" } ], "time_range": { "start_time": {START_TIME_IN_SECONDS}, "end_time": {END_TIME_IN_SECONDS} } }
Aggregation search request contains following fields:
entity_type : Use the entity types defined in AllEntityType enum in the API Reference.
filter : Format of the filter expression is defined above.
aggregations: It contains array of elements. Each element consists of a field and aggregation type. Field should be a valid property of the entity. And aggregation type can be one of the following.
· SUM
· MAX
· MIN
· AVG
time_range: Time range consists of start_time and end_time. Both should be POSIX epochs (The number of seconds elapsed since Jan 1st 1970).
· start_time
· end_time
Finding total number of CPU cores and overall total memory of all the Virtual Machines
{ "entity_type":"VirtualMachine", "aggregations": [ { "field": "cpu_count", "aggregation_type": "SUM" }, { "field": "memory", "aggregation_type": "SUM" } ] }
Finding total memory of the Virtual Machines containing 'app' in their name
{ "entity_type": "VirtualMachine", "filter": "name like 'app'", "aggregations": [ { "field": "cpu_count", "aggregation_type": "SUM" }, { "field": "memory", "aggregation_type": "SUM" } ] }
Find sum of bytes of all flows from 10th Nov 2018 to 20th Nov 2018
{ "entity_type": "Flow", "aggregations": [ { "field": "flow.totalBytes.delta.summation.bytes", "aggregation_type": "SUM" } ], "time_range": { "start_time": 1541808000, "end_time": 1542672000 } }
Find sum of bytes of all flows from 1.1.1.1 to 2.2.2.2 from 10th Nov 2018 to 20th Nov 2018.
{ "entity_type": "Flow", "filter": "source_ip.ip_address = '1.1.1.1' and destination_ip.ip_address = '2.2.2.2'", "aggregations": [ { "field": "flow.totalBytes.delta.summation.bytes", "aggregation_type": "SUM" } ], "time_range": { "start_time": 1541808000, "end_time": 1542672000 } }
Find max, min and sum memory of virtual machines
{ "entity_type": "VirtualMachine", "aggregations": [ { "field": "cpu_count", "aggregation_type": "MAX" }, { "field": "cpu_count", "aggregation_type": "SUM" } ] }

Group By

URL: /api/ni/search/groupby
{ "entity_type": "{ENTITY_TYPE}", "filter": "{FILTER}”, "aggregations": [ { "field": "{FIELD}", "aggregation_type": "{AGGREGATION_TYPE}" } ], “group_by”: [String], “sort_by”: [ { "field": "{FIELD}", "aggregation_type": "{AGGREGATION_TYPE}", “order”: {ASC} } ], "time_range": { "start_time": {START_TIME_IN_SECONDS}, "end_time": {END_TIME_IN_SECONDS}, }, “size”: 0, “cursor”: string }
Group By Request contains following fields: entity_type: Use the entity types defined in AllEntityType enum in the API Reference. filter: Format of the filter is same as above. aggregations: It contains array of elements. Each element consists of a field and aggregation type. Field should be a valid property of the entity and aggregation type can be one of the following. . SUM . MAX . MIN . AVG group_by: It contains array of elements. Each element is field which is valid property of entity. sort_by: It contains array of elements. Each element consists of field, aggregation type and optional order (ASC / DESC). time_range: Time range consist of start_time and end_time. Both should be POSIX epohcs (The number of seconds elaspsed since JAN 1st 1970). . start_time . end_time
Examples:
Find avg of CPU cores group by sum of CPU cores in ascending order
{ "entity_type": "VirtualMachine", "aggregations": [{ "field": "cpu_count", "aggregation_type": "AVG" }], "group_by": ["cpu_count"], "sort_by": [{ "field": "cpu_count", "aggregation_type": "SUM", "order": "ASC" }], "time_range": { "start_time": 1570612016, "end_time": 1570612016 } }
Find sum of bytes of all flows from 1.1.1.1 to 2.2.2.2 from 10th Nov 2018 to 20th Nov 2018 group by source ip and destination ip order by maximum of flow in ascending order
{ "entity_type": "Flow", "filter": "source_ip.ip_address = '1.1.1.1' and destination_ip.ip_address = '2.2.2.2'", "aggregations": [ { "field": "flow.totalBytes.delta.summation.bytes", "aggregation_type": "SUM" } ], "sort_by": [{ "field": "flow.totalBytes.delta.summation.bytes", "aggregation_type": "MAX", "order": "ASC" }], "group_by": ["destination_ip", "source_ip"], "time_range": { "start_time": 1541808000 , "end_time": 1542672000 } }
Operators
Operator
Description
=
Equals
!=
Not Equals
>
Greater Than
<
Less Than
>=
Greater Than OR Equals
<=
Less Than OR Equals
LIKE
Value contains the the field value
IN
Value matches one of the field values in list
NOT IN
Value does not match any field value in list
SET
Value is not null
NOT SET
Value is null
FIELD_VALUE
The search value can be a string, integer, list of strings or list of integers.
For example:
  • String: 'securitygroup-10'
  • Integer : 211

Examples of Search

Sample Search Requests
Find VMs with a specific ip_address, such as 192.168.10.1:
Request POST https://operations-for-networks.example.com/api/ni/search Request Body { "entity_type": "VirtualMachine", "filter": "ip_addresses.ip_address = '192.168.10.1'", }
Find all VMs on a host with name 'host-a'
Request POST https://operations-for-networks.example.com/api/ni/search Request Body { "entity_type": "VirtualMachine", "filter": "host.name = 'host-a'", }
Find all VMs in the NSX security group with moref 'securitygroup-10'
Request POST https://operations-for-networks.example.com/api/ni/search Request Body { "entity_type": "VirtualMachine", "filter": "security_groups.vendor_id = 'securitygroup-10'", }
Find all VMs where the name is 'vm-a' or 'vm-b' or 'vm-c'
Request POST https://operations-for-networks.example.com/api/ni/search Request Body { "entity_type": "VirtualMachine", "filter": "name IN ('vm-a', 'vm-b', 'vm-c')", }
Find all VMs where the default gateway is set
Request POST https://operations-for-networks.example.com/api/ni/search Request Body { "entity_type": "VirtualMachine", "filter": "default_gateway is set", }
Find all VMs in host 'host-a' and security group 'sg-1'
Request POST https://operations-for-networks.example.com/api/ni/search Request Body { "entity_type": "VirtualMachine", "filter": "((security_groups.name = 'sg-1') and (host.name = 'host-a'))", }
Find all VMs in security group sg-1 and that do not have network address '192.168.10.0/24'
Request POST https://operations-for-networks.example.com/api/ni/search Request Body { "entity_type": "VirtualMachine", "filter": "((security_groups.name = 'sg-1') and (ip_addresses.network_address != '192.168.10.0/24'))", }