GraphQL in ColdFusion

Learn about GraphQL in ColdFusion, how it is different from REST, GraphQL schema, variables and parameters.

What is GraphQL?

GraphQL gives you all the information you need about your API data and allows clients to request exactly what they need.

Some of the benefits of GraphQL API include: 

  • Query multiple data sources at once.
  • Retrieve only the data you need.
  • Easily change or add data.

How is GraphQL different from REST?

REST is an architectural style for creating web services, while GraphQL is a query language for APIs. 

GraphQL is much more powerful than REST, as it allows you to query specific data and get only the data you need. Unlike REST based APIs, GraphQL allows you to customize your data return, and the query structure mimics the structure of the JSON which returns.

When to use GraphQL?

Under-fetching and over-fetching 
When you know your users will have limited bandwidth, you can use GraphQL to request exactly the data you need without making multiple requests.

Optimize data transfer 
You can use GraphQL when we have a client-heavy application and need to optimize the data transfer between client and server.

Consumes less bandwidth 
GraphQL consumes less bandwidth as it makes a single API call to get precise data. So, you can use it when you want to optimize bandwidth. This can be a boon when dealing with very large, highly verbose applications such as social media, messaging, and SMS based programs.

Core Concepts

A GraphQL request string is called a GraphQL document. For example,

{
  author {
    id
    name
  }
}

You can utilize a GraphQL query by importing it into a page to use as a query, or by writing the query inline inside your code.

GraphQL client methods

GetGraphQLClient 

Syntax

getGraphQLClient(parameterStruct) 

Description

Use this method to create the GraphQL client that will communicate with the server that contains the schema. Pass the configuration parameters to get the client.

Parameters

Parameter Description Required
service_url The URL of the server, which contains the schema. You can create your own server or use any of the existing ones. For more information, see the following:  Yes
service_name
Specify the name of the server. 
Yes
client_name The name of the GraphQL client that you had configured in the ColdFusion Administrator. For more information on configuring the GraphQL service on the ColdFusion Administrator, see GraphQL options. Yes
raw_http_client 
(True/False) Attribute to specify whether you must use HTTP Client or Apollo Client internally. 
No
root_package_name
Specifies the root of your server. For example, if you have two servers, create both the folders in cfusion/gql/main/src, and then you will refer the folders in your pom.xml. The root folder must be unique for each GraphQL service. 
No
headers

A struct containing:

  • keys: The key to authenticate with the server.
  • values: The value to authenticate with the server.
Yes
batching_configuration 

Batching is required by the GraphQL Client to reduce the number of network round trips by enabling multiple operations in a single HTTP call.

The param is struct of the following:

  • enabled: (True/False) Whether batching is enabled.
  • batch_interval_ms: The interval (in milliseconds) between each call.
  • max_batch_size: Specify the number of calls to be sent in a batch.

If you want batching, then enabled is required. The rest are optional. 

No
subscription_configuration 
A struct of the following: 
  • websocket_url: For subscriptions, the communication is through WebSockets, therefore, specify the URL. The websocket url can be different from the server url.
  • subscription_heartbeat_timeout: Specify the subscription timeout value.
  • subscription_heartbeat_timeunit: Specify the timeout unit.

If you want subscription, then websocket_url is required. 

No

Exceptions

Exception Description
ValidationException
When config is null/incorrect.
ModuleNotAvailableException
When graphqlclient module is not installed.

For example,

Inline

// Create GQL object 
gqlClient = getGraphQLClient({ 
    service_url : "ENDPOINTURL", 
    "raw_http_client" : true 
}); 
// This variable will hold your GQL query 
Gql = ‘ 
query  
    { 
        Table  
            {  
                Column1  
                Column2 
                Column3 
                Column4 
            } 
        } 
‘ 
// Assign the response from your query to a variable so you can dump it to screen 
response = gqlClient.fetchResponse(gql1, {}); 

File

gqlClient = getGraphQLClient ({ 
  service_name: "server-name", 
  type = "graphqlclient", 
  "raw_http_client": true, 
  service_url : "endpoint-url", 
  root_folder: "root_folder", 
  headers : { 
      values: "auth-value", 
      keys: "auth-key" 
  }, 
batching_configuration: { 
    		enabled: true, 
    		batch_interval_ms: 10, 
    		max_batch_size: 15 
}, 
subscription_configuration : { 
   		websocket_url: "wss://websocket-url", 
    		subscription_heartbeat_timeout : 5, 
    		subscription_heartbeat_timeunit : "nano" 
} 
}) 

GenerateGraphQLModels 

Syntax

generateGraphQLModels() 

Description

This method generates models for all queries, mutations, and subscriptions. Call this method every time if there is a change in the query or you’ve added a new query in the graphql file.

If there are errors, stop ColdFusion, clear the Felix cache (CFHOME\cfusion\bin\felix-cache), and restart ColdFusion.

GraphQL object methods 

The GraphQL objects contains the method, fetchResponse. The method retrieves the response of the specified query to the server. 

Syntax 

fetchResponse(query, queryParams) 

Parameters 

  • query: The query, subscription, or mutation to be passed to the server.
  • queryParams: The values to pass as query parameters.

Exceptions

  • org.apache.maven.shared.invoker.MavenInvocationException

For example,

paramValues = ${id:[89,109,189,200,205]};

response = gqlclient.fetchResponse("mutation BookTrip($id:[ID]!) {bookTrips(launchIds:$id) {success message}}", paramValues);

GraphQL client methods 

The following methods are supported: 

Method Parameters Returns
activeCallsCount() 
None Number of calls made to the query 

addOnSubscriptionManagerStateChangeListener

(com.apollographql.apollo.subscription.OnSubscriptionManagerStateChangeListener) 

Closure function None
disableSubscriptions() 
None None
downloadSchema(java.lang.String, java.lang.String) 
Schema of the query None
enableSubscriptions() 
None None
getApplicationInterceptorFactories() 
None List
getApplicationInterceptors() 
None List
getName() 
None Name of the query
getSchema(java.lang.String) 
None Returns the GraphQL schema
getServerUrl() 
None The URL of the GraphQL server
getSubscriptionManager() 
None The subscription manager
getSubscriptionManagerState() 
None The state of the subscription manager.
mutation(java.lang.String, java.lang.Object) 
  1. Name of the mutation
  2. Struct containing data to add
Mutation object
query(java.lang.String, java.lang.Object) 
  1. Schema
  2. Struct of data to a query
Query object
serverOk() 
None Status of the server, True if server is running, False otherwise
shutDown() 
None None
startBatchPoller() Non
None None
stopBatchPoller() 
None None
subscribe(java.lang.String, java.lang.Object) 
  1. Schema
  2. Struct data for subscription
None

Query/Mutation/Subscription object  

You can obtain the object for the operations by creating an object of the function, getGraphQLClient. For example,  

// get the graphQL service first 
     gqlClient = getGraphQLClient({ 
      service_Url : "https://apollo-fullstack-tutorial.herokuapp.com/graphql", 
      root_folder: "root", 
  //"raw_http_client": true, 
  headers: { 
    		  keys: "key", 
    		  values: "value"     	  } 

    }); 
    generateGraphQLModels();     
    queryObj = gqlClient.query(schema,values)

Query object methods  

The following methods are supported: 

Method Parameters Returns
canBeBatched(boolean) 
boolean 
Returns the query object. 
cancel() 
None None
clone() 
None Returns the cloned object of the operation. 
enqueue(closure) 
enqueue(), execute() would be available on queryObject methods. They would be called on queryObject.execute() or mutationObject.enqueue(onSuccess, onFailure). There would be two closures, one for success, other for failure in enqueue() 
None
execute() 
None Returns the results from the query object. 
fields() 
None Returns the fields of the query response.
isCanceled() 
None Returns if an operation is canceled (True) or not (False). 
marshalVariablesJson() 
None Returns JSON data. 
opName() 
None Returns the name of the query, mutation, or subscription operation. 
operation() 
None Returns the type of operation. 
rawOperation() 
None Returns a string. 
toBuilder() 
None Returns ApolloCall.Builder<T> object. 
variables() 
None Returns a struct of the variables used in the operation. 

Mutation object methods  

The following methods are supported: 

Method Parameters Returns
canBeBatched(boolean)
Note: Mutations are not supported in batching.
boolean Returns the query object. 
cancel() 
None None
clone() 
None Returns the cloned object of the operation. 
enqueue(closure) 
Callback to handle any logic of a query operation. For example, OnResponse, OnFailure, OnHTTPError, and so on. 
None
execute() 
None
Returns the results from the query object. 
fields() 
None
Returns the fields of the query response. 
isCanceled() 
None
Returns if an operation is canceled (True) or not (False). 
marshalVariablesJson() 
None
Returns JSON data. 
opName() 
None
Returns the name of the query, mutation, or subscription operation. 
operation() 
None
Returns the type of operation. 
rawOperation() 
None
Returns a string. 
toBuilder() 
None
Returns ApolloCall.Builder<T> object. 
variables() 
None
Returns a struct of the variables used in the operation. 

Subscription object methods  

The following methods are supported: 

Method Parameters Returns
cancel() 
None None
clone() 
None Returns the cloned object of the operation. 
execute(closure,closure,closure) 
Callback to handle any logic of a query operation. For example, OnResponse, OnFailure, OnHTTPError, and so on. 
None
execute(Closure onConnected, Closure onResponse, subscriptionObject.closure onFailure,Closure onCompleted, Closure onTerminated) 
Callback to handle any logic of a query operation. For example, OnResponse, OnFailure, OnHTTPError, and so on. 
 
isCanceled() 
None Returns if an operation is canceled (True) or not (False). 

Configure GraphQL client

ColdFusion Administrator

Configuring the GraphQL service using the ColdFusion Administrator. For more information, see GraphQL options.

<cfscript>
	adminObj = CreateObject("component","CFIDE.adminapi.administrator");
	adminObj.login("admin","admin")
	
	gqlCFC = CreateObject("component","CFIDE.adminapi.graphql")
	
	http_header = {
		"x-hasura-admin-secret" = "secret"
	}
	    gqlCFC.setServiceConfiguration(service_name="hasura",root_package_name="root_hasura",service_url="https://hardy-mink-39.hasura.app/v1/graphql",headers=http_header, schema_path="");
	sc = {
        websocket_url: "wss://hardy-mink-39.hasura.app/v1/graphql",
        subscription_heartbeat_timeout : "1",
        subscription_heartbeat_timeunit : "days"
    }
    bc = {
        enabled: false
    }
	gqlCFC.setClientConfiguration(client_name="hasura_client_http",service_cname="hasura",raw_http_client=true,batching_configuration=bc, subscription_configuration=sc);
	gqlCFC.updateServiceConfiguration(service_name="hasura",raw_http_client=true, root_package_name="updated_root");
	gqlCFC.updateClientConfiguration(client_name="hasura_client_http",raw_http_client=false);
	gqlFC.deleteServiceConfiguration("hasura"); Deleting service will delte clients as well
	gqlFC.deleteClientConfiguration("hasura_client_http");
	
</cfscript>

What is a GraphQL Schema?

GraphQL API endpoints that you will be consuming will have their functionality constrained by a schema. Schemas are JSON descriptions of what is allowable on a GraphQL endpoint.

A schema is a description of an item that can also be referred to as a representation of a query. Any GraphQL server implementation is built around a GraphQL schema. It outlines a GraphQL server's functionalities, such as the range of queries, modifications, subscriptions, and additional types and directives that can be used. 

A hierarchy of types with fields filled in from your backend data storage is defined by the schema. Also, it describes the data that clients may access, write, or remove from the server.

Basic concepts of a schema  

You write a GraphQL schema GraphQL SDL (schema definition language), also called GraphQL schema language.

A schema defines a collection of types and the relationships between them. There are four basic GraphQL types: 

  • Scalar
  • Object- Query, Mutation, and Subscription
  • Input
  • Enum

Write a GraphQL schema   

Before writing a schema, have the following ready:

  • Structure and fields
  • Field types and return types
  • Type of operation,query, mutation, or both

Here is an example of how we can use the schema to define a simple type called Person: 

type Person {
  name: String!
  age: Int!
}

The schema has two fields, name and age, and has the data types, String and Int respectively. 

A Person, in turn, can also be a part of a Post.

type Post {
  title: String!
  author: Person! 
}

For more information, see GraphQL Schema.

GraphQL operations 

The following are the types of GraphQL operations:

  • query (a read-only fetch)
  • mutation (a write followed by a fetch)
  • subscription (a request that fetches data in response to events)

Query

A GraphQL query retrieves data from the application server like a REST GET call. GraphQL queries satisfy a range of use cases, including the following: 

  • A set of products to be displayed.
  • Display customer data. 
  • Shopping cart contents.

Structure of a query

A query contains the following elements: 

  • The optional keyword query. 
  • An operation name for your local implementation. This name is required if you include variables.
  • The name of the query.
  • The terms to search for. 
  • The output object, which specifies which data the query returns.

The following example shows the structure of the cart query:

query myCartQuery{
  cart(cart_id: String!): Cart
}

MyCartQuery in the example above indicates how you implemented the cart query. The string with the non-nullable value cart id identifies the cart to query. The value is not nullable, as shown by the exclamation point. The fields to return are specified by the Cart output object.

The following is the full query:

query myCartQuery{ 
  cart(cart_id: "1WxKm8WUm3uFKXLlHXezew5WREfVRPAn") { 
    items { 
      id 
      quantity 
    } 
    billing_address { 
      firstname 
      lastname 
      postcode 
      } 
    shipping_addresses { 
      firstname 
      lastname 
      postcode 
    } 
  } 
} 

The following example shows the query response: 

{ 
  "data": { 
    "cart": { 
      "items": [ 
        { 
          "id": "7", 
          "quantity": 10 
        } 
      ], 
      "billing_address": { 
        "firstname": "James", 
        "lastname": "Spencer", 
        "postcode": "12345" 
      }, 
      "shipping_addresses": [ 
        { 
          "firstname": "James", 
          "lastname": "Spencer", 
          "postcode": "12345" 
        } 
      ] 
    } 
  } 
} 

When defining a query, you can also implement the following:

Async and sync

ColdFusion supports async operations in GraphQL, where you can execute an operation in the client, and run an operation in a concurrent thread. For example,

onSuccess = function(response) { 
writeOutput("Received Response from GraphQL Server"); 
writedump(response.toString()); 
} 
onError = function() { 
writeOutput("Error While Receiving Response from GraphQL Server"); 
}  
queryObj = gqlClient.query("Warriors", {});    
// async call 
queryObj.enqueue(onSuccess, onError);  
// sync call 
writedump(queryObj.execute()) 

In async versions, for Query and Mutation operations, we’re providing the following callback methods:

  • onSuccess
  • onFailure

If there is a success from the server, the onSuccess callback is invoked. Else, the onFailure callback is invoked.

Variables in GraphQL 

Pass a variable as shown in the example below: 

query ($limit: Int) { 
  author(limit: $limit) { 
    id 
    name 
  } 
} 

The variable can be set in the following way: 
{ 
  limit: 5 
} 

Variables in GraphQL 

In GraphQL, you can insert, update or delete data with mutations. A mutation is a GraphQL Operation that allows you to modify data on the server-side. You can think of GraphQL mutations like POST, PUT, PATCH, and DELETE requests in REST.

For example,

mutation { 

  addCategory(id: 6, name: "Green Fruits", products: [8, 2, 3]) { 
    name 
    products { 
      name 
    } 
  } 
} 

Subscription

Subscriptions are useful for notifying your client in real time about changes to back-end data, such as the creation of a new object or updates to an important field. 

For example,

type Subscription { 
  commentAdded(postID: ID!): Comment 
} 

On the client side, 
subscription OnCommentAdded($postID: ID!) { 
    commentAdded(postID: $postID) { 
      id 
      content 
    } 
  } 

How subscriptions work

Subscriptions use websockets to set up real-time communication from the server to the client. A subscription listens to websockets when a query creates, reads, updates, or deletes data on the server. The events are pushed from the server to the subscribing clients.

The callback functions supported are:

  • public void execute(Closure onResponse, Closure onFailure, Closure onCompleted); 
  • public void execute(Closure onConnected, Closure onResponse, Closure onFailure,Closure onCompleted, Closure onTerminated)

For example,

<cfscript>  

    //Subscription Client Handle Creation 
    subscrClient = getGraphQLClient({ 
    		url = <graphql_server_url>, 
    	        webSocketServerUrl = <websocket_server_url>, 
    	        wsprotocol = <websocket_protocol>, 
    	        subscriptionTrasportFactory = <subscription_transport_factory>, 
    	        headers = <ok_http_client> 
    ... 
    }); 

    subscriptionHandlerCallback = <Callback to Handle the 	    OnCompleted/OnConnected/OnTerminated/OnResponse/OnFailure Logic for Subscription Operation>  
    subscriptionCall = subscrClient.subscribe(subscriptionObj);  
    subscriptionCall.execute(subscriptionHandlerCallback); 
 </cfscript> 

GraphQL in ColdFusion 

For this release, install the full version of ColdFusion and the GraphQL package will get installed automatically. 

Note:

For naming the Graphql files, the name of the operation provided must match the operation name provided while forming the query object. 

Location of the GraphQL files

In this document, the examples use the Apollo server.

If {cfusion.home} is the location of ColdFusion home, then:

  • For service1, all .graphql files need to be placed in {cfusion.home}/src/main/graphql/service1 directory.
  • For service2, all .graphql files need to be placed in {cfusion.home}/src/main/graphql/service2 directory.
Note:

‘myservice’ is a service that is packaged with the graphqlclient package. The xml entry for 'myservice' will also be listed in pom.xml. If you want to create your own service, create a folder in the same directory (/cfusion/gql/src/main/graphql/{new_gql_service_name}), and modify the pom.xml file to add the new service. 

Changes in pom.xml

The pom.xml (ColdFusion/cfusion-home/gql) is overwritten with the service endpoint entry added.

<myservice>
    <compilationUnit>
        <name>myservice</name>

        <compilerParams>
            <rootPackageName>root</rootPackageName>
        </compilerParams>
    </compilationUnit>

    <introspection>
        <enabled>true</enabled>

        <endpointUrl
            >https://apollo-fullstack
            tutorial.herokuapp.com/graphql</endpointUrl
        >

        <headers></headers>

        <connectTimeoutSeconds>10</connectTimeoutSeconds>
        <readTimeoutSeconds>10</readTimeoutSeconds>
        <writeTimeoutSeconds>10</writeTimeoutSeconds>
        <useSelfSignedCertificat>false</useSelfSignedCertificat>
        <useGzip>false</useGzip>
        <prettyPrint>false</prettyPrint>
    </introspection>
</myservice>

HTTP Client and Apollo Client

In Apollo Client, you can write the queries and place the queries in the service folder that you’ve created. Then on the cfm file, invoke the method generateGraphQLModels(), and generate the response.

Whereas using a http client, you can write and edit the query directly without compiling the query. A http client does not support subscription. In addition, a http client doesn't perform type checking of parameters at the client side.

Query 

A query is used by the client to request the data it needs from the server. 

For example,

Calculate the number of launches. 

<cfscript> 
    // get the graphQL service first 
     gqlClient = getGraphQLClient({ 
      service_Url : "https://apollo-fullstack-tutorial.herokuapp.com/graphql", 
      root_folder: "root", 
  	  headers : { 
    		  keys: "Authorization", 
    		  values: "value" 
    	  } 
    }); 
    generateGraphQLModels();	 
    queryObj = gqlClient.query("MissionDetails", {});	 
    response=queryObj.execute() 
    response.get("Data") 
</cfscript> 

Similarly, calculate the number of trips booked, 

<cfscript> 
    // get the graphQL service first 
     gqlClient = getGraphQLClient({ 
      service_Url : "https://apollo-fullstack-tutorial.herokuapp.com/graphql", 
      root_folder: "root", 
 	  headers : { 
    		  keys: "Authorization", 
    		  values: "value" 
    	  } 
    }); 
    generateGraphQLModels(); 
    queryObj = gqlClient.query("TripsBooked", {}); 
    //writedump(queryObj); 
    response=queryObj.execute() 
   // writeDump(response.get("Data")) 
</cfscript> 

Output

{totalTripsBooked=9} 

Subscription

TripsBookedSub.graphql 

subscription TripsBookedSub { 
  tripsBooked 
} 

File.cfm 

<cfscript> 
    gqlClient = getGraphQLClient({ 
      service_Url : "https://apollo-fullstack-tutorial.herokuapp.com/graphql", 
      root_folder: "root", 
  	  headers : { 
    		  keys: "Authorization", 
    		  values: "value" 
    	  } 
    }); 

    generateGraphQLModels();  
    queryObj=gqlClient.subscribe("TripsBookedSub",{}) 
    // writeDump(queryObj)     
</cfscript> 

Mutation

Mutations return a fetch THAT you can specify. You cannot mutate without a return.

Add a user login.

Login.graphql

mutation Login($email: String) { 
  login(email: $email) { 
    token 
  } 
} 

mutation.cfm 

<cfscript> 

    gqlClient = getGraphQLClient({ 
      service_Url : "https://apollo-fullstack-tutorial.herokuapp.com/graphql", 
      root_folder: "root", 
      //"raw_http_client": true, 
      headers : { 
    		  keys: "key", 
    		  values: "value" 
    	  } 
    }); 
    generateGraphQLModels(); 
    queryObj = gqlClient.mutation("Login", { 
                            "email": "user1@example.com" 
    }); 

    // writedump(queryObj)   
    response=queryObj.execute() 
    // writeDump(response.get("Data")) 
</cfscript> 

Output

{

    login=Login{

        __typename=User, token=<token>

    }

}

Fragment

A fragment is a reusable query component is a GraphQL fragment. You could encounter circumstances in GraphQL when you need to use different queries to look for the same fields. If your query contains numerous repeating fields spread across several different locations, you can combine them into a single, reusable unit known as a fragment.

The following is a declaration of a EmpName fragment that can be used with any Employee object:

fragment EmpName on Employee { 
  firstName 
  lastName 
} 

For example,

LaunchDetailsFragment.cfm

fragment launchFragment on Launch { 
  id 
  site 
  mission { 
    name 
  } 
} 
query LaunchDetailsFragment($id:ID!) { 
  launch(id: $id) { 
    # Usage of named fragment 
    ...launchFragment 
  } 
} 

fragments.cfm 

<cfscript> 
    gqlClient = getGraphQLClient({ 
      service_Url : "https://apollo-fullstack-tutorial.herokuapp.com/graphql", 
      root_folder: "root", 
      headers : { 
    		  keys: "key", 
    		  values: "value" 
    	  } 
    }); 
    generateGraphQLModels();  
    queryObj = gqlClient.query("LaunchDetailsFragment", {"id": "50"}); 
    // writedump(queryObj) 
    response=queryObj.execute() 
    // writeDump(response.get("Data")) 
</cfscript> 

Output

{launch=Launch{__typename=Launch, fragments=Fragments{launchFragment=LaunchFragment{__typename=Launch, id=50, site=KSC LC 39A, mission=Mission{__typename=Mission, name=KoreaSat 5A}}}}} 

Inline parameters

The ColdFusion implementation of GraphQL allows you to pass in queries and parameters inline directly in your CFML code. This can help with readability when debugging, as well as make it easier to pass in variables from the CF scope into your query parameters. 

For example,

<cfscript> 
    // get the graphQL service first 
    gqlClient = getGraphQLClient({ 
   service_Url : " https://apollo-fullstack-tutorial.herokuapp.com/graphql ", 
    "raw_http_client": true, 
    headers : { 
        keys: "key", 
 	values: "value" 
    } 
    }); 
    paramValues = ${launchId: 1}; // define the values to be passed in the query 
    response = gqlclient.fetchResponse(" 
    query TripsBooked($launchId: ID!) { 
    launch(id: $launchId) { 
        id 
        isBooked 
        mission { 
          name 
    } 
  } 
}  
",paramValues); 
    writeOutput(response.get("Data")) 
</cfscript> 

Output

{"data":{"launch":{"id":"1","isBooked":false,"mission":{"name":"FalconSat"}}}}

Pagination

In GraphQL, fetch all necessary data fields from the server in a single query, eliminating any unnecessary overhead in terms of network response time and payload size. Unfortunately, there is no guarantee that these improvements will always occur, particularly when working with lists of structured data that have unpredictable lengths. If you ask for the complete list, which has the potential to include an unlimited number of elements, you can get delayed answers with very large payloads. Using pagination or selectively querying a list, solves this.

For example,

teacher { 

    name 

    students (first:5) { 

      name 

    } 

  } 

} 

Use the arguments, limit and offset, to display results, one page at a time.

For example,

students (limit:5, afterID:152) { 

  id 

  name 

} 

Batching

A GraphQL client required batching to reduce the number of round trips in a network. Batching is performed by enabling multiple operations in a single HTTP call.

By default, Batching will be enabled for all the operations on a batched client, however an operation can opt out by invoking canbeBatched(false) operation before calling the execute method.

Note:

Batching is available only for Query operations.

ColdFusion supports the following batching parameters: 

"batching_configuration":{ 

            "enabled": true, // whether to enable batching on a query, mutation, or subscription 

            "batch_interval_ms": 1000, // The interval (in milliseconds) between each call. 

            "max_batch_size": 2 //  

 } 

Batching functions

The following batching-related functions are supported:

startBatchPoller

Description

Starts the polling mechanism to check for queued queries to batch and send as a single HTTP call. For the function to work, you must enable “enabled”:true in the batch configuration settings.

Syntax

gqlClient.startBatchPoller() 

For example,

<cfscript> 

    gqlClient = getGraphQLClient({ 

      service_Url : "https://apollo-fullstack-tutorial.herokuapp.com/graphql", 

      root_folder: "root", 

  //"raw_http_client": true, 

  headers : { 

    		keys: "Authorization", 

    		values: "a2FsbHVAZ21haWwuY29t" 

      }, 

      "batching_configuration":{ 

            "enabled": true, 

            "batch_interval_ms": 1000, 

            "max_batch_size": 2 

      } 

    }); 

    generateGraphQLModels();  

    writedump(gqlClient) 

    queryObj = gqlClient.query("TripsBooked", {}) 

    writedump(queryObj); 

    response=queryObj.execute() 

    writeDump(response.get("Data")) 

    

    // define the error and success closure functions 

     onSuccess = function(response) { 

        writeOutput("<br>Received Response from GraphQL Server----------<br>"); 

        writeOutput(response.toString()); 

    } 

    onError = function() { 

        writeOutput("<br>Error While Receiving Response from GraphQL Server<br>"); 

    } 

    writeOutput("<br/>"& "Active calls count" & "<br/>") 

    writeOutput(gqlClient.activeCallsCount()) 

    writeOutput("<br/>"& "Can be batched" & "<br/>") 

    gqlClient.startBatchPoller(); 

    queryObj.canBeBatched(true) 

</cfscript> 

stopBatchPoller

Description

Stops the polling mechanism to check for queued queries to batch. For the function to work, you must enable “enabled”:true in the batch configuration settings.

Syntax

gqlClient.stopBatchPoller()

For example,

<cfscript> 

    gqlClient = getGraphQLClient({ 

      service_url : "https://apollo-fullstack-tutorial.herokuapp.com/graphql", 

      root_folder: "root", 

  //"raw_http_client": true, 

  headers : { 

    		keys: "key", 

    		values: "value" 

      }, 

      "batching_configuration":{ 

            "enabled": true, 

            "batch_interval_ms": 1000, 

            "max_batch_size": 2 

      } 

    }); 

    generateGraphQLModels(); 

  

    writedump(gqlClient) 

    queryObj = gqlClient.query("TripsBooked", {}) 

    writedump(queryObj); 

    response=queryObj.execute() 

    writeDump(response.get("Data")) 

    

    // define the error and success closure functions 

     onSuccess = function(response) { 

        writeOutput("<br>Received Response from GraphQL Server----------<br>"); 

        writeOutput(response.toString()); 

    } 

    onError = function() { 

        writeOutput("<br>Error While Receiving Response from GraphQL Server<br>"); 

    } 

    writeOutput("<br/>"& "Active calls count" & "<br/>") 

    writeOutput(gqlClient.activeCallsCount()) 

    writeOutput("<br/>"& "Can be batched" & "<br/>") 

    gqlClient.startBatchPoller(); 

    queryObj.canBeBatched(true) 

    gqlClient.stopBatchPoller(); 

</cfscript> 

canBeBatched(bool)

Decription

Determines whether a query can be batched.

Syntax

GqlClient.canBeBatched(bool batchedTrueOrFalse)

Parameter

  • batchedTrueOrFalse: True if you want to batch, False otherwise.

Example of batching

LaunchList.graphql

query LaunchList { 
  launches { 
    cursor 
    hasMore 
    launches { 
      id 
      site 
    } 
  } 
} 

LaunchDetailsFragment.graphql 

fragment launchFragment on Launch { 

  id 

  site 

  mission { 

    name 

  } 

} 

  

query LaunchDetailsFragment($id:ID!) { 

  launch(id: $id) { 

    # Usage of named fragment 

    ...launchFragment 

  } 

} 

File.cfm

Output

<cfscript> 
    gqlClient = getGraphQLClient({ 
      service_Url : "https://apollo-fullstack-tutorial.herokuapp.com/graphql", 
      root_folder: "root", 
  //"raw_http_client": true, 
  headers : { 
    		keys: "key", 
    		values: "value" 
      }, 
      "batching_configuration":{ 
            "enabled": true, 
            "batch_interval_ms": 1000, 
            "max_batch_size": 2 
      } 
    }); 

    generateGraphQLModels(); 
    writedump(gqlClient) 
    queryObj = gqlClient.query("LaunchList",{cursor:"1583556631"}); 

    writedump(queryObj); 

    response=queryObj.execute() 

    writeDump(response.get("Data"))  

    queryObj2 = gqlClient.query("LaunchList", {cursor:""});  

    queryObj3 = gqlClient.query("LaunchDetailsFragment",[id:"89"]); 

    response3=queryObj3.execute() 

    writeDump(response3.get("Data")) 

    //queryObj4 = gqlClient.query("LaunchDetailsFragment",[id:"90"]); 

    gqlClient.startBatchPoller();  

    queryObj.canBeBatched(true);	 

    queryObj2.canBeBatched(true);	 

    queryObj3.canBeBatched(true);	 

    gqlClient.stopBatchPoller(); 

    writeOutput("Completed");  

</cfscript> 

Output

{launches=Launches{__typename=LaunchConnection, cursor=1583556631, hasMore=true, launches=[Launch{__typename=Launch, id=110, site=KSC LC 39A}, Launch{__typename=Launch, id=109, site=CCAFS SLC 40}, Launch{__typename=Launch, id=108, site=VAFB SLC 4E}, Launch{__typename=Launch, id=107, site=KSC LC 39A}, Launch{__typename=Launch, id=106, site=CCAFS SLC 40}, Launch{__typename=Launch, id=105, site=CCAFS SLC 40}, Launch{__typename=Launch, id=104, site=KSC LC 39A}, Launch{__typename=Launch, id=103, site=KSC LC 39A}, Launch{__typename=Launch, id=102, site=KSC LC 39A}, Launch{__typename=Launch, id=101, site=CCAFS SLC 40}, Launch{__typename=Launch, id=100, site=CCAFS SLC 40}, Launch{__typename=Launch, id=99, site=KSC LC 39A}, Launch{__typename=Launch, id=98, site=CCAFS SLC 40}, Launch{__typename=Launch, id=97, site=CCAFS SLC 40}, Launch{__typename=Launch, id=96, site=CCAFS SLC 40}, Launch{__typename=Launch, id=95, site=CCAFS SLC 40}, Launch{__typename=Launch, id=94, site=KSC LC 39A}, Launch{__typename=Launch, id=93, site=KSC LC 39A}, Launch{__typename=Launch, id=92, site=KSC LC 39A}, Launch{__typename=Launch, id=91, site=CCAFS SLC 40}]}} {launch=Launch{__typename=Launch, fragments=Fragments{launchFragment=LaunchFragment{__typename=Launch, id=89, site=CCAFS SLC 40, mission=Mission{__typename=Mission, name=Starlink 3}}}}} 

 Adobe

Get help faster and easier

New user?

Adobe MAX 2024

Adobe MAX

The Creativity Conference

Oct 14–16 Miami Beach and online

Adobe MAX 2024

Adobe MAX

The Creativity Conference

Oct 14–16 Miami Beach and online