--- title: Query your change tracking data source: https://docs.newrelic.com/docs/change-tracking/query-data --- After setting up change tracking and viewing your changes in the New Relic UI, you can create custom queries to analyze change patterns, build dashboards, and set up automated reporting. This page shows you how to query change tracking data using NRQL and NerdGraph. New Relic provides both [NRQL](https://docs.newrelic.com/docs/nrql/get-started/introduction-nrql-new-relics-query-language/) and [NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/) as to query change tracking data, each suited for different use cases. ## Use NRQL for change tracking [#use-nrql] Use [NRQL](https://docs.newrelic.com/docs/nrql/get-started/introduction-nrql-new-relics-query-language/) to: - **Create dashboards**: Build custom charts and visualizations for ongoing monitoring. - **Analyze time-series data**: Correlate changes with performance metrics over time. - **Set up alerts**: Create alert conditions based on change patterns. - **Perform statistical analysis**: Calculate averages, percentages, and trends. The following data sources are available for NRQL queries: - `ChangeTrackingEvent`: Events created using the new `changeTrackingCreateEvent` mutation. - `Deployment`: Legacy deployment events created using `changeTrackingCreateDeployment` as well as our legacy REST APIs. > #### 💡 TIP > > If you want to query your deployments for both change tracking events and legacy deployments, you can use the following NRQL query pattern: > > ````sql > FROM ChangeTrackingEvent, Deployment > SELECT eventType(), deploymentId OR changeTrackingId AS 'id', * > WHERE (eventType() = 'Deployment' OR (eventType() = 'ChangeTrackingEvent' AND category = 'Deployment')) > AND entity.name = '' > ``` > > > ```` ### NRQL query examples [#nrql-examples] Use these examples in the [query builder](https://docs.newrelic.com/docs/query-your-data/explore-query-data/query-builder/introduction-query-builder/) or when creating dashboards and alerts. > #### 💡 TIP > > For complete attribute definitions, see our [data dictionary](/attribute-dictionary/?dataSource=Change+tracking). #### For change events **Run a basic query to get change events for last week** ````sql SELECT * FROM ChangeTrackingEvent SINCE 1 week ago ``` ```` **Compare transaction errors to change markers for an application for the last month** ````sql SELECT count(*) FROM TransactionError WHERE appName = 'INSERT_YOUR_APP_NAME' AND http.statusCode > 300 SINCE 1 month ago TIMESERIES ``` ```` #### For change deployments (Legacy) **Run a basic query to get changes for the past thirty days** ````sql SELECT * FROM Deployment SINCE 30 days ago ``` ```` **List transactions errors for the past month** ````sql SELECT count(*) FROM TransactionError WHERE appName = 'INSERT_YOUR_APP_NAME' AND http.statusCode > 300 SINCE 1 month ago TIMESERIES ``` ```` **Query transaction performance to correlate with change markers** ````sql SELECT count(*) FROM Transaction WHERE appName = 'INSERT_YOUR_APP_NAME' FACET name LIMIT MAX SINCE 1 week ago TIMESERIES ``` When you chart this query in dashboards or use it in the query builder, New Relic will automatically overlay your deployment markers on the time series chart, allowing you to visually correlate transaction performance with your tracked changes. ```` ## Use NerdGraph for change tracking [#use-graphql] Use [NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/) when you want to: - **Programmatic access**: Integrate change data into external tools and workflows. - **Cross-account queries**: Retrieve data from multiple New Relic accounts. - **Real-time applications**: Build applications that need live change data. - **Bulk data export**: Extract large datasets for analysis in external systems. The NerdGraph API offers several advantages for querying change tracking data: - Access to related entity information - Advanced filtering capabilities - Cross-account data aggregation - Real-time API responses ### NerdGraph query examples [#graphql-examples] Use these examples in the [NerdGraph explorer](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/nerdgraph-explorer) or in your applications. #### For change events **List a set of events across all accounts for the past hour** ````graphql { actor { changeTracking { changeTrackingSearch { changeEvents { shortDescription category changeTrackingId customAttributes description groupId timestamp type user } } } } } ``` ```` **Filter change event data by \`timeWindow\`, \`accountIds\`, and entity guid \`query\`** ````graphql { actor { changeTracking { changeTrackingSearch( filter: { timeWindow: { startTime: INSERT_MS_EPOCH_TIMESTAMP endTime: INSERT_MS_EPOCH_TIMESTAMP } accountIds: INSERT_ACCOUNT_IDS query: "entity.guid = 'INSERT_ENTITY_GUID'" } ) { changeEvents { shortDescription category type changeTrackingId customAttributes description groupId timestamp user entity { guid accountId } } } } } } ``` ```` **Filter with query and limits** ````graphql { actor { changeTracking { changeTrackingSearch( filter: { query: "user = 'ChangeTrackingUser'", limit: 10 } ) { changeEvents { shortDescription category type changeTrackingId customAttributes description groupId timestamp user } } } } } ``` ```` #### For change deployments (Legacy) **List version, entityGuid, and timestamp** ````graphql { actor { entity(guid: "INSERT_YOUR_GUID_HERE") { deploymentSearch( filter: { timeWindow: { endTime: INSERT_MS_EPOCH_TIMESTAMP startTime: INSERT_MS_EPOCH_TIMESTAMP } } ) { results { version entityGuid timestamp } } } } } ``` ```` **List a variety of fields by a specific user** ````graphql { actor { entity(guid: "INSERT_YOUR_GUID_HERE") { deploymentSearch( filter: { timeWindow: { endTime: INSERT_MS_EPOCH_TIMESTAMP startTime: INSERT_MS_EPOCH_TIMESTAMP } query: "user = 'Test User'" } ) { results { version entityGuid timestamp changelog commit deepLink deploymentId description deploymentType groupId user } } } } } ``` ```` **List a variety of fields by a specific version and change type** ````graphql { actor { entity(guid: "INSERT_YOUR_GUID_HERE") { deploymentSearch( filter: { timeWindow: { endTime: INSERT_MS_EPOCH_TIMESTAMP startTime: INSERT_MS_EPOCH_TIMESTAMP } query: "((user = 'Test User' AND version = '1.0') OR deploymentType IN ('BLUE_GREEN', 'CANARY'))" limit: 200 } ) { results { changelog commit deepLink deploymentId deploymentType description entityGuid groupId timestamp user version } } } } } ``` ```` ### NerdGraph optimization tips [#graphql-optimization] - **Request only needed fields**: Specify only the fields you actually need - **Use appropriate filters**: Apply filters server-side rather than client-side - **Batch related queries**: Combine related queries in a single request - **Implement pagination**: Use limit and cursor-based pagination for large datasets ## Data retention and limits [#data-retention-limits] Understanding data constraints helps you plan your analysis approach: | Data type | Retention | | ---------------------- | ---------------------------------- | | Change events | 13-month retention period | | Chart markers | Up to 5,000 events per chart | | Change tracking tables | 1,000 events loaded by default | | Custom trend boards | Maximum of 3 per change | | Comparison views | Up to 5 stacked change comparisons | ## Related documentation [#related-docs] [Notify your team](https://docs.newrelic.com/docs/change-tracking/change-tracking-webhooks) Learn how to set up notifications for your change tracking events. [Introduction to Change Tracking](https://docs.newrelic.com/docs/change-tracking/overview) Get an overview of change tracking concepts and benefits. [View and analyze changes](https://docs.newrelic.com/docs/change-tracking/view-analyze-data) Learn how to view and analyze your change tracking data.