Documentation Home

Queries

An overview of singular, plural and metric data queries

The bulk of queries to the Native-X API can be divided into the following three categories:

  • Singular Data Queries

  • Plural Data Queries

  • Metric Data Queries

To provide as high level of an overview of how to use these queries we're going to focus on the following queries for each respective category:

  • publisher (Singular Data Queries)

  • allPublishers (Plural Data Queries)

  • dailyCampaignMetrics and publisherMetricBreakouts (Metric Data Queries)

Singular Data Queries

To understand how to perform a singular data query, let's take a look at the publisher query. Here is an example:

The following example only includes of subset of all the possible fields that can be returned via this query, for a more thorough overview of the available fields and what data they contain please consult An Outline of Types more specifically the Publisher type.

query publisher($input: ModelIdInput!, $startDate: Date!, $endDate: Date!) {
  publisher(input: $input) {
    id
    name
    website
    logo {
      src
    }

    topics {
      totalCount
      edges {
        node {
          id
          name
          placements {
            edges {
              node {
                id
                name
                
                metrics (start: $startDate, end: $endDate) {
                  ctr
                  clicks
                  views
                }
                
              }
            }
          }
        }
      }
    }

    campaigns(pagination: { first: 1 }) {
      totalCount
      edges {
        node {
          id
          name
          hash
          
          advertiser {
            id
            name
            externalId
          }
          
          creatives {
            id
            title
          }
          
          criteria {
            start
            end
          }
          
          metrics {
            ctr
            views
            clicks
          }
          
          reports {
            byDay(startDate: $startDate, endDate: $endDate){
              day(format: "MMMM D YYYY")
              metrics {
                ctr
                views
                clicks
              }
            }
          }
          
        }
      }
    }

    emailDeployments {
      totalCount
      edges {
        node {
          id
          name
        }
      }
    }

    metrics(start: $startDate, end: $endDate ) {
      ctr
      views
      clicks
    }

  }
}

Lets take a more condensed look at this working with just Campaigns for a given Publisher:

Note: This query makes an assumption to paginate to a subsequent "page" after retrieving an initial set of results with the return of Campaigns.pageInfo.endCursor for use in a previousCursor variable.

query publisher($input: ModelIdInput!, $startDate:Date!, $endDate: Date!, $previousCursor: Cursor!) {
  publisher(input: $input) {
    id
    name
    campaigns(pagination: {first: 5, after: $previousCursor}) {
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
      edges {
        node {
          id
          name
          hash
          
          advertiser {
            id
            name
            externalId
          }
          
          creatives {
            id
            title
          }
          
          criteria {
            start
            end
          }
          
          metrics {
            ctr
            views
            clicks
          }
          
          reports {
            byDay(startDate: $startDate, endDate: $endDate){
              day(format: "MMMM D YYYY")
              metrics {
                ctr
                views
                clicks
              }
            }
          }
          
        }
      }
    }
  }
}

This example query could be done perpetually until there are no longer any Campaigns query for. By default the first value for the pagination input is 25 so in the event you have a totalCount less than that for any query pagination becomes unnecessary. This will typically be indicated by pageInfo.hasNextPage being set to false.

Plural Data Queries

To understand how to perform a plural data query, let's take a look at the allPublishers query. Here is an example:

Note: The following example is condensed to demonstrate the nature of a "plural" query the overall field definitions are the same as their singular counterpart, with the addition of a wrapping Connection for more information on Connection and other data types please consult An Outline of Types and more particularly What is a connection? for information regarding the Connection schema type.

query {
  allPublishers {
    totalCount
    edges {
      node {
        id
        name
      }
    }
  }
}

Metric Data Queries

Lastly we'll quickly cover a couple examples of Metric Data Queries using dailyCampaignMetrics and publisherMetricBreakouts

query dailyCampaignMetrics($day: Date!) {
  dailyCampaignMetrics(day: $day) {
    campaigns
    views
    clicks
    ctr
  }
}
query publisherMetricBreakouts($input: BreakoutMetricsInput!, $sort:PublisherMetricsSortInput){
publisherMetricBreakouts(input:$input, sort:$sort) {
    publisherName
    views
    clicks
    ctr
  }
}

PreviousAn Outline of Inputs

Last updated