Entities at New Relic refer to anything we monitor that generates or contains telemetry. Entities help you find the data you want to track in New Relic, and if you understand their relationships with other entities, you can get even more insights into your data. Here are a few examples of entities:

• Applications monitored byAPM.
• Cloud integrations, services, and hosts monitored by ourinfrastructure monitoring.

You can work with entities right in our UI (seeLearn about New Relic entities), or you can follow the steps here about working with entities through our NerdGraph API. If you need help getting started with NerdGraph, see ourIntroduction to New Relic NerdGraph.

Before you get started

Before working with entities, we recommend readingLearn about entities.

When working with entities, some important things to keep in mind:

• A unique GUID identifies an entity (entity.guid orentityGuid).
• An entity exists in New Relic for aspecific time period.
• An entity provides a useful entry point for exploring data about specific metrics and events or for contextualizing data related to other entities.

Search for entities

New Relic searches for entities by their attributes, primarily their name, but also by type of entity and other values. The search returns basic data about entities matching the search criteria. Then, from the basic query results, you can query a specific entity by its GUID.

BesidesdomainType, other common entity attributes are:

• id
• accountId
• name
• domainId
• alertSeverity
• reporting

You can filter by any of the above attributes. Additionally, you can usetags for filtering.

You can craft a query in one of two ways:

1. Use thequeryBuilder argument to help you craft a query.
2. Use the freeformquery argument to build your own search.

To use NerdGraph to query one or more entities, you can search by attribute or GUID.

In addition tothe examples below, we recommend that you experiment with the API using theNerdGraph explorer. It has inline documentation that will help you construct your queries and mutations.

Search withqueryBuilder

ThequeryBuilder argument is useful to construct simple queries. It allows you to add filters to your query from a predefined list of attributes, and their typical values. For more advanced queries, use thequery argument instead.

1. Go to the NerdGraphGraphiQL explorer.

2. Run a basic query to find entities that match your search criteria. For example:

   {
   actor{
   entitySearch(queryBuilder:{domain:APM,type:APPLICATION}){
   query
   results{
   entities{
   name
   entityType
   guid
   }
   }
   }
   }
   }

   Copy

Search with freeformquery

This is useful to craft more complex queries.

1. Go to the NerdGraphGraphiQL explorer.

2. Run a basic query to find entities that match your search criteria. For example:

   query($query:String!){
   actor{
   entitySearch(query:$query){
   count
   results{
   entities{
   name
   entityType
   guid
   }
   }
   }
   }
   }

   Copy

3. Add the followingvariables to theQuery variables section in NerdGraph:

   {"query":"name LIKE 'nerd-graph' AND domainType IN ('APM-APPLICATION')"}

   Copy

Fetch entities by GUID

When you know the GUID of the entity you want to fetch, you can just use theentity attribute:

{
actor{
entity(guid:"ENTITY_GUID"){
name
entityType
}
}
}

This can also be written as a search query:

{
actor{
entitySearch(query:"id = 'ENTITY_GUID'"){
query
results{
entities{
name
entityType
}
}
}
}
}

Or, to fetch multiple entities at the same time, you can use theentities attribute:

{
actor{
entities(guids:["ENTITY_GUID_1","ENTITY_GUID_2"]){
name
entityType
}
}
}

Otherwise, use a search query:

{
actor{
entitySearch(query:"id IN ('ENTITY_GUID_1', 'ENTITY_GUID_2')"){
query
results{
entities{
name
entityType
}
}
}
}
}

Example queries

Queries are requests that are intended to only fetch data (and don't have any other effect). NerdGraph queries are not static, meaning that you can ask for more or less data depending on your needs. For each query, you can specify exactly what data you want to retrieve, as long as it's supported by the schema.

Entities in NerdGraph rely onGraphQL interfaces, a concept that allows objects to share common fields. Interfaces are used to provide data for specific entity types, as you will see in many of these NerdGraph query examples.

{
actor{
entitySearch(query:"name like 'nerdgraph'"){
results{
entities{
name
tags{
key
values
}
}
}
}
}
}

{
actor{
entitySearch(
query:"domain = 'INFRA' and tags.aws.awsRegion = 'us-east-1'"
){
results{
entities{
name
}
}
}
}
}

{
actor{
entitySearch(
query:"domainType = 'BROWSER-APPLICATION' and tags.clusterAgentId is not null"
){
results{
entities{
name
}
}
}
}
}

{
actor{
entitySearch(query:"domainType = 'APM-APPLICATION'"){
facetedCounts(facets:{facetCriterion:{facet:ACCOUNT_ID}}){
counts{
count
facet
}
}
}
}
}

{
actor{
entitySearch(
query:"domainType = 'APM-APPLICATION' and tags.aws.awsRegion = 'us-east-1'"
){
facetedCounts(facets:{facetCriterion:{tag:"language"}}){
counts{
count
facet
}
}
}
}
}

Create or delete entity relationships

An entity may have a relationship with another entity. Some relationships arecreated automatically by New Relic, but you can also use mutations to create or delete custom relationships. We have some explanations below about how to do this, but if you need help understanding the various relationship types at New Relic, take a look atEntity relationships.

Before you manually create additional relationships or delete them, keep the following in mind:

• Two entities can have multiple relationships, one for each relationship type.
• Two entities can hold a relationship IF they belong to the same trusted account.
• For each entity, you can manually define up to 2000 relationships. When the limit is reached, the API will return aLIMIT_EXCEEDED error.
• Each mutation can fail if you don't have access to one of the two entities (source/target).

List relationships of an entity

You can use therelatedEntities field to see how pairs of entities interact and how they're related. This can help you troubleshoot upstream and downstream services and understand how minor issues may have larger repercussions, similar to howservice maps can be used.

The following example shows how to query an entity by its specific GUID:

query{
actor{
entity(guid:"ENTITY_GUID"){
name
relatedEntities{
results{
source{
entity{
guid
name
}
}
target{
entity{
guid
name
}
}
type
}
}
}
}
}

Create or replace relationships

Create or replace entity relationships using the mutationentityRelationshipUserDefinedCreateOrReplace. As its name suggests, it allows you to create a relationship between two entities with a given type. If the relationship already exists between the two entities, it will be added again with the updated given values (the creation time and the creator user id):

mutation{
entityRelationshipUserDefinedCreateOrReplace(
sourceEntityGuid:"SOURCE_ENTITY_GUID"
targetEntityGuid:"TARGET_ENTITY_GUID"
type:BUILT_FROM
){
errors{
message
type
}
}
}

Delete relationships

Delete entity relationships using the mutationentityRelationshipUserDefinedDelete. The source and target are mandatory, but the type isn't. If you execute the mutation without type, all the relationships between the two entities are removed.

mutation{
entityRelationshipUserDefinedDelete(
sourceEntityGuid:"SOURCE_ENTITY_GUID"
targetEntityGuid:"TARGET_ENTITY_GUID"
type:BUILT_FROM
){
errors{
message
type
}
}
}

Delete entities

You can manually delete any entity in your account by using the NerdGraph API in theNerdGraph GraphiQL explorer.

To deleteEXT-SERVICE andREF-REPOSITORY entities, run this mutation with the entity's GUID:

mutation{
entityDelete(guids:["ENTITY_GUID_1","ENTITY_GUID_2"]){
deletedEntities
failures{
guid
message
}
}
}

To deleteAPM,BROWSER andMOBILE entities, run this mutation with the entity's GUID:

mutation{
agentApplicationDelete(guid:"ENTITY_GUID"){
success
}
}