Workspace Tab

⚡ GraphQL Builder Guide

What It Does

GraphQL Builder is a dedicated tool for composing and executing Salesforce GraphQL queries. Built on CodeMirror 6, it provides syntax highlighting, smart formatting, variable support, and real-time error detection — everything you need to explore your org's data and metadata through Salesforce's GraphQL API.

Salesforce GraphQL (built on the UI API) is a powerful alternative to SOQL. Use it to fetch related records efficiently in a single request, query metadata alongside data, or build more flexible queries with complex filtering and nested selections that would require multiple SOQL queries.

When to use GraphQL: Fetching related records (e.g., Account with Opportunities and Contacts in one request), querying records with complex relationships, exploring metadata, testing UI API implementations.

Getting Started

Open the TrackForcePro workspace and click the GraphQL tab. You'll see a two-pane layout:

  • Left Pane — Query editor (CodeMirror 6) where you write your GraphQL query.
  • Right Pane — Variables panel (JSON) and response explorer. Responses appear here after you run your query.

No setup needed — just start writing a query and you're ready to execute against your org.

Code Editor (CodeMirror 6)

The query editor on the left is a professional code editor built for GraphQL. Write queries directly or paste them from other tools. The editor supports Salesforce's GraphQL schema and provides intelligent assistance.

Editor Features

  • Syntax Highlighting — GraphQL keywords (query, mutation, subscription), field names, types, and variables are color-coded for readability and error detection.
  • Auto-Indentation — The editor automatically indents nested query structures as you type, making complex queries readable.
  • Bracket Matching — Click or hover over curly braces or parentheses to highlight their matching pair. Helps catch missing brackets.
  • Line Numbers — Reference specific query lines when discussing or debugging syntax errors.
  • Theme Adaptation — The editor respects your light/dark mode preference for comfortable coding at any time of day.

Query Structure

Salesforce GraphQL queries follow the UI API pattern. Most queries start with the uiapi root, followed by the operation (query, mutation, etc.):

Basic pattern:
query GetAccounts { uiapi { query { Account { edges { node { Id Name BillingCity } } } } } }

With relationships:
query GetAccountsWithOpps { uiapi { query { Account { edges { node { Id Name Opportunities { edges { node { Id StageName } } } } } } } } }

Tip: Copy working queries from other GraphQL clients (like Salesforce's own GraphQL endpoint explorer or Postman) and paste them here. TrackForcePro executes them against your org immediately.

Variables & Parameterized Queries

The Variables panel (top-right) holds JSON-formatted variable definitions that parameterize your GraphQL query. This pattern lets you keep your query template static and swap in different values without rewriting the entire query.

How Variables Work

  • Define Variables as JSON — Enter variable definitions as a valid JSON object. Each key-value pair becomes a variable available in your query.
  • Reference with $ — In your GraphQL query, reference variables using $variableName syntax.
  • Type Safety — GraphQL validates that variable types match the query's parameter types. Type mismatches produce clear error messages.
  • Optional Variables — Leave the Variables panel empty if your query has no parameters. Variables are entirely optional.

Examples

Simple Variable:

Variables: { "accountId": "001D000000IRFmaIAH" }

Query: query GetAccount($id: String!) { uiapi { query { Account(where: { Id: { eq: $id } }) { edges { node { Id Name } } } } } }
Search with Pattern:

Variables: { "searchTerm": "Acme" }

Query: query SearchAccounts($term: String!) { uiapi { query { Account(where: { Name: { like: $term } }) { edges { node { Id Name BillingCity } } } } } }

Workflow: Write a parameterized query once, then change only the variables to run the same query against different data. Perfect for repeated analysis or batch operations.

Running Queries

Execute your GraphQL query against your Salesforce org using either method:

  • Click the Run button at the top of the editor pane.
  • Press Ctrl+Enter (Windows/Linux) or Cmd+Enter (macOS).

GraphQL Builder validates your query syntax and variables before sending them to Salesforce. If there are validation errors (missing fields, type mismatches, schema violations), you'll see a clear error message. Once validated and executed, your response appears in the right panel.

What Happens Behind the Scenes

  1. Your query and variables are sent to Salesforce's GraphQL endpoint via your authenticated session.
  2. Salesforce validates the query against the org's schema and executes it.
  3. The response (data or errors) returns and is displayed with formatting and error highlighting.
  4. Execution time and HTTP status code appear in the response header for performance analysis.
First-time tip: Start with a simple query (e.g., fetch 5 Account records with just Id and Name). This verifies your connection works before building complex nested queries.

Response Explorer & Error Handling

The response panel displays the result of your GraphQL query with professional formatting and error detection. Whether your query succeeds or fails, you get clear, actionable feedback.

Success Responses

  • Formatted JSON — Results are pretty-printed with color-coded syntax highlighting and smart indentation for readability.
  • Collapsible Sections — Expand or collapse nested objects and arrays to drill into the parts you care about. Useful for exploring complex relationship hierarchies.
  • Status Header — Shows HTTP status code (200 OK), execution time in milliseconds, and response size.
  • Copy Functions — Select and copy response sections for use in other tools or documentation.

Error Responses

When a query fails, errors appear with detailed explanations. Common errors include:

Error Message Cause & Fix
Cannot query field "X" on type "Y" Field doesn't exist or is not queryable on that object. Check the Salesforce GraphQL schema or Field-level Security permissions.
Expected Name, found "}" Syntax error in your query (missing field name, mismatched brackets). Review the line number and check brackets and commas.
Variable $X is not defined Your query references a variable that isn't in the Variables panel. Add it to the Variables JSON object.
Type mismatch for variable $X Variable value type doesn't match the query's parameter type (e.g., passing a string where an integer is expected). Check the query type definition and variable value.
Access denied Your user lacks permission to query that field or object. Check Field-Level Security and Object permissions in Setup.

Debugging tip: Copy the error message and use Salesforce's GraphQL documentation to validate your query structure. The line number in the error message points you to the problem area.

Tips, Tricks & Best Practices

Query Construction

  • Start Minimal, Build Up — Begin with the simplest possible query: fetch 3–5 Account records with just Id and Name. Verify it works, then add relationships and fields incrementally. This prevents getting buried in complex syntax errors.
  • UI API Pattern — Most Salesforce GraphQL queries follow the uiapi { query { ObjectName { edges { node { fields } } } } } pattern. If you're new to Salesforce GraphQL, study this structure in the documentation.
  • Use WHERE Clauses for Filtering — Add filtering logic in your GraphQL query (e.g., Account(where: { Name: { like: "Acme" } })) rather than fetching all records and filtering client-side. Salesforce filters on the server, which is much faster.

Variables & Parameterization

  • Variables for Reusability — If you'll run the same query 5+ times with different IDs or search terms, define variables. Update only the Variables JSON instead of rewriting the entire query each time.
  • Variable Naming — Use descriptive variable names ($accountId, $searchTerm, $pageSize) to make parameterized queries self-documenting.
  • Type Definitions — In your query, declare variable types explicitly (e.g., query($id: String!)). The ! means required; omit it for optional variables.

Performance & Optimization

  • Select Only Needed Fields — GraphQL's strength is precise data fetching. Include only fields you actually need in your response. Fewer fields = smaller response size = faster response time.
  • Limit Related Records — When fetching relationships (e.g., Opportunities for an Account), use pagination or LIMIT-like constructs to avoid returning 10,000 related records. A query like Opportunities(first: 10) returns only the first 10.
  • Test Before Large Queries — Always validate your query on a small sample first (e.g., fetch 1 Account with all your relationships). Once you confirm it works, you can scale safely.

GraphQL vs. SOQL

  • Use GraphQL for Relationships — Fetching an Account with its Opportunities, Contacts, and Cases in one request is much cleaner in GraphQL than SOQL (which requires 4 separate queries).
  • Use SOQL for Simple Bulk Queries — If you need 5000 Accounts in a simple list, SOQL is faster and simpler than GraphQL. GraphQL is more powerful but slightly more verbose for bulk data extraction.
  • Metadata Queries — GraphQL is excellent for querying both data and metadata together (e.g., a Contact's fields and available field values in a single request).

Common Patterns

Fetch Account with Recent Opportunities:
query { uiapi { query { Account(where: {Id: {eq: "001..."}}) { edges { node { Id Name Opportunities(first: 5) { edges { node { Id Name StageName } } } } } } } } }
Search Contacts by Email Domain:
query($domain: String!) { uiapi { query { Contact(where: {Email: {like: $domain}}) { edges { node { Id Name Email } } } } } }

Variables: { "domain": "%@acme.com" }
💡 Pro Tip: Save successful query templates in a text file or wiki. GraphQL schema is stable within your org — reusing proven templates saves 10+ minutes per query and virtually eliminates syntax errors. Build a personal library of common patterns.