Pusher

Introduction to how our GraphQL mutations function and some additional sample mutations, along with any need to know details

Things you Should Know

The pusher is a special tool, considering it let's you upload your own data into the pulsar-verse with ease. It's not surprising there are a few special things to keep in mind:

  • You can submit a single piece of content to multiple searches in one query; just identify more search hashes in the array of searches variable

  • There are two primary fields to pass arguments to: validateInteraction and storeInteraction. The former is for testing your data for errors before submitting it to make sure it passes Pulsar's checks. The latter is for actually submitting data to the platform. Both will return a list of errors with your mutation call (if any), but only the latter actually submits your data.

  • Unlike the CSV uploader, partial successes are not possible; if your data set has any errors you will need to correct them or remove the content at the indexes triggering the errors. You can use the validator to confirm your data is in an acceptable format.

  • The pusher takes time! Don't expect to upload your data and immediately be able to query and sort on it. Give the pusher some time to index your data. Even after being indexed, it may take a little more time for your data to be analyzed. It's important to remember the pusher isn't simply a "data-in, data-out" tool. It's a method of bringing data together within the constraints of a curated search.

What Does a Mutation Call Look Like?

A GraphQL mutation has two parts: the call, and the mutation variables.

The call (displayed on the first tab below) first gets a defined name, and the arguments (variables) being passed in to the types within the query.

Then in here, using the schema, you define the fields you want as a part of that call.

Each field has its own special schema that provides a list of subfields and variables needed to specify what should be returned.

mutation FPDTest($interactions: [Interaction!]!, $searches: [String!]!) {
  storeInteraction(interactions: $interactions, searches: $searches){
    errors
    message
    status
  }
}

The variables are used to fill in the parameters as seen above.

These are also defined using the schema, but the formatting style for this data is called JSON.

{
  "interactions": {
    "content": {
      "body": "I love submitting via the API!",
      "publishedAt": "2020-11-11T00:00:00Z",
      "remoteId": "1123581321"
    }
  },
  "searches":[
    "searchhash"
  ]
}

What Does A Payload Look Like?

A returned payload can vary based on whether you are pushing or validating data to push, but you will be sent back some form of a JSON with information relevant to the call made.

For example, in test to validate data, like this:

mutation FPDValidTest($interactions: [Interaction!]!, $searches: [String!]!) {
  validateInteraction(interactions: $interactions, searches: $searches){
    errors
    message
    status
  }
}

You might see a return that looks like this:

{
  "data": {
    "validateInteraction": {
      "errors": [],
      "message": "Valid",
      "status": 200
    }
  }
}

Or one like this if your data is invalid:

{
  "errors": [
    {
      "message": "Variable $interactions of type [Interaction!]! was provided invalid value for 0.content.publishedAt (Could not coerce value \"2020-11-1100:00:00\" to ISO8601DateTime)",
      "locations": [
        {
          "line": 1,
          "column": 18
        }
      ],
      "extensions": {
        "value": {
          "content": {
            "body": "I love submitting via the API!",
            "publishedAt": "2020-11-1100:00:00",
            "remoteId": "1123581321"
          }
        },
        "problems": [
          {
            "path": [
              0,
              "content",
              "publishedAt"
            ],
            "explanation": "Could not coerce value \"2020-11-1100:00:00\" to ISO8601DateTime"
          }
        ]
      }
    }
  ]
}

Note that the formatting is the same as the variables for a mutation: JSON.

The validation field makes it easy to sense check your data for errors before submitting and the JSON return makes it easy to see where in your data the errors were

Sample Calls - Intro

Below are a handful of sample calls to help you understand how the pusher API works when pushing and validating data

Each sample call will contain the mutation performed and variables in one tab, followed by the Response in the other.

We do this to keep formatting consistent with how most API testing environments would surface the blocks as groups.

Creating a Search from Scratch

This is currently not supported by the GraphQL API, but can be accomplished via the REST API. Learn more here.

Validating Content - Success

mutation FPDValidateS($dataType: Int, $interactions: [Interaction!]!, $searches: [String!]!) {
  validateInteraction(dataType: $dataType, interactions: $interactions, searches: $searches){
    errors
    message
    status
  }
}
{
	"interactions":[ 
    {
		  "author" : {
        "name":"Dominick DiPulsar",
        "screenName": "@dompulsar",
        "remoteId": "domdipulsar"
      },
      "content": {
			  "body": "Here is my first piece of content",
			  "publishedAt": "2020-11-12T04:53:00Z",
			  "remoteId": "1123581321",
        "counters": {
          "likes": 512,
          "shares": 23
        },
        "type": "post"
		  }
	  },
    {
		  "author" : {
        "name":"Francesco Pulsario",
        "screenName": "@fpulsario",
        "remoteId": "franpulsario"
      },
      "content": {
			  "body": "Here is my second piece of content",
			  "publishedAt": "2020-11-12T04:57:00Z",
			  "remoteId": "1123581322",
        "counters": {
          "likes": 121,
          "shares": 10
        },
        "type": "post"
		  }
	  },
    {
		  "author" : {
        "name":"Linda Pulsuta",
        "screenName": "@lindapuls",
        "remoteId": "lpulsuta"
      },
      "content": {
			  "body": "Here is my third piece of content",
			  "publishedAt": "2020-11-12T04:56:00Z",
			  "remoteId": "1123581323",
        "counters": {
          "likes": 2331,
          "shares": 68
        },
        "type": "post"
		  }
	  },
    {
		  "author" : {
        "name":"Nirain Pulsel",
        "screenName": "@nirpulsel",
        "remoteId": "npulsel"
      },
      "content": {
			  "body": "Here is my fourth piece of content",
			  "publishedAt": "2020-11-12T05:03:00Z",
			  "remoteId": "1123581324",
        "counters": {
          "likes": 99,
          "shares": 84
        },
        "type": "post"
		  }
	  },
    {
		  "author" : {
        "name":"Jean Pulso",
        "screenName": "@jpulso",
        "remoteId": "jeanpulso"
      },
      "content": {
			  "body": "Here is my fifth piece of content",
			  "publishedAt": "2020-11-12T05:05:00Z",
			  "remoteId": "1123581325",
        "counters": {
          "likes": 197,
          "shares": 33
        },
        "type": "post"
		  }
	  }
  ],
	"searches": [
		"searchhash"
  ]
}

Validating Content - Errors Found

mutation FPDValidateS($dataType: Int, $interactions: [Interaction!]!, $searches: [String!]!) {
  validateInteraction(dataType: $dataType, interactions: $interactions, searches: $searches){
    errors
    message
    status
  }
}
{
	"interactions":[ 
    {
		  "author" : {
        "name":"Dominick DiPulsar",
        "screenName": "@dompulsar",
        "remoteId": "domdipulsar"
      },
      "content": {
			  "body": "Here is my first piece of content",
			  "publishedAt": "2020-11-12T04:53:00Z",
			  "remoteId": "1123581321",
        "counters": {
          "likes": 512,
          "shares": 23
        },
        "type": "post"
		  }
	  },
    {
		  "author" : {
        "name":"Francesco Pulsario",
        "screenName": "@fpulsario",
        "remoteId": "franpulsario"
      },
      "content": {
			  "body": "Here is my second piece of content",
			  "publishedAt": "2020-11-12T04:57:00Z",
			  "remoteId": "1123581322",
        "counters": {
          "likes": 121,
          "shares": 10
        },
        "type": "nonsense"
		  }
	  },
    {
		  "author" : {
        "name":"Linda Pulsuta",
        "screenName": "@lindapuls",
        "remoteId": "lpulsuta"
      },
      "content": {
			  "body": "Here is my third piece of content",
			  "publishedAt": "2020-11-12T04:56:00Z",
			  "remoteId": "1123581323",
        "counters": {
          "likes": 2331,
          "shares": 68
        },
        "type": "post"
		  }
	  },
    {
		  "author" : {
        "name":"Nirain Pulsel",
        "screenName": "@nirpulsel",
        "remoteId": "npulsel"
      },
      "content": {
			  "body": "Here is my fourth piece of content",
			  "publishedAt": "2020",
			  "remoteId": "1123581324",
        "counters": {
          "likes": 99,
          "shares": 84
        },
        "type": "post"
		  }
	  },
    {
		  "author" : {
        "name":"Jean Pulso",
        "screenName": "@jpulso",
        "remoteId": "jeanpulso"
      },
      "content": {
			  "body": "Here is my fifth piece of content",
			  "publishedAt": "2020-11-12T05:05:00Z",
			  "remoteId": "1123581325",
        "counters": {
          "likes": 197,
          "shares": 33
        },
        "type": "post"
		  }
	  }
  ],
	"searches": [
		"searchhash"
  ]
}

Submitting Several Pieces of Content - Success

mutation FPDstore($dataType: Int, $interactions: [Interaction!]!, $searches: [String!]!) {
  storeInteraction(dataType: $dataType, interactions: $interactions, searches: $searches){
    errors
    message
    status
  }
}
{
	"interactions":[ 
    {
		  "author" : {
        "name":"Dominick DiPulsar",
        "screenName": "@dompulsar",
        "remoteId": "domdipulsar"
      },
      "content": {
			  "body": "Here is my first piece of content",
			  "publishedAt": "2020-11-12T04:53:00Z",
			  "remoteId": "1123581321",
        "counters": {
          "likes": 512,
          "shares": 23
        },
        "type": "post"
		  }
	  },
    {
		  "author" : {
        "name":"Francesco Pulsario",
        "screenName": "@fpulsario",
        "remoteId": "franpulsario"
      },
      "content": {
			  "body": "Here is my second piece of content",
			  "publishedAt": "2020-11-12T04:57:00Z",
			  "remoteId": "1123581322",
        "counters": {
          "likes": 121,
          "shares": 10
        },
        "type": "post"
		  }
	  },
    {
		  "author" : {
        "name":"Linda Pulsuta",
        "screenName": "@lindapuls",
        "remoteId": "lpulsuta"
      },
      "content": {
			  "body": "Here is my third piece of content",
			  "publishedAt": "2020-11-12T04:56:00Z",
			  "remoteId": "1123581323",
        "counters": {
          "likes": 2331,
          "shares": 68
        },
        "type": "post"
		  }
	  },
    {
		  "author" : {
        "name":"Nirain Pulsel",
        "screenName": "@nirpulsel",
        "remoteId": "npulsel"
      },
      "content": {
			  "body": "Here is my fourth piece of content",
			  "publishedAt": "2020-11-12T05:03:00Z",
			  "remoteId": "1123581324",
        "counters": {
          "likes": 99,
          "shares": 84
        },
        "type": "post"
		  }
	  },
    {
		  "author" : {
        "name":"Jean Pulso",
        "screenName": "@jpulso",
        "remoteId": "jeanpulso"
      },
      "content": {
			  "body": "Here is my fifth piece of content",
			  "publishedAt": "2020-11-12T05:05:00Z",
			  "remoteId": "1123581325",
        "counters": {
          "likes": 197,
          "shares": 33
        },
        "type": "post"
		  }
	  }
  ],
	"searches": [
		"searchhash"
  ]
}

Submitting Several Pieces of Content - Errors Found

mutation FPDstore($dataType: Int, $interactions: [Interaction!]!, $searches: [String!]!) {
  storeInteraction(dataType: $dataType, interactions: $interactions, searches: $searches){
    errors
    message
    status
  }
}
{
	"interactions":[ 
    {
		  "author" : {
        "name":"Dominick DiPulsar",
        "screenName": "@dompulsar",
        "remoteId": "domdipulsar"
      },
      "content": {
			  "body": "Here is my first piece of content",
			  "publishedAt": "2020-11-12T04:53:00Z",
			  "remoteId": "1123581321",
        "counters": {
          "likes": 512,
          "shares": 23
        },
        "type": "post"
		  }
	  },
    {
		  "author" : {
        "name":"Francesco Pulsario",
        "screenName": "@fpulsario",
        "remoteId": "franpulsario"
      },
      "content": {
			  "body": "Here is my second piece of content",
			  "publishedAt": "2020-11-12T04:57:00Z",
			  "remoteId": "1123581322",
        "counters": {
          "likes": 121,
          "shares": 10
        },
        "type": "nonsense"
		  }
	  },
    {
		  "author" : {
        "name":"Linda Pulsuta",
        "screenName": "@lindapuls",
        "remoteId": "lpulsuta"
      },
      "content": {
			  "body": "Here is my third piece of content",
			  "publishedAt": "2020-11-12T04:56:00Z",
			  "remoteId": "1123581323",
        "counters": {
          "likes": 2331,
          "shares": 68
        },
        "type": "post"
		  }
	  },
    {
		  "author" : {
        "name":"Nirain Pulsel",
        "screenName": "@nirpulsel",
        "remoteId": "npulsel"
      },
      "content": {
			  "body": "Here is my fourth piece of content",
			  "publishedAt": "2020",
			  "remoteId": "1123581324",
        "counters": {
          "likes": 99,
          "shares": 84
        },
        "type": "post"
		  }
	  },
    {
		  "author" : {
        "name":"Jean Pulso",
        "screenName": "@jpulso",
        "remoteId": "jeanpulso"
      },
      "content": {
			  "body": "Here is my fifth piece of content",
			  "publishedAt": "2020-11-12T05:05:00Z",
			  "remoteId": "1123581325",
        "counters": {
          "likes": 197,
          "shares": 33
        },
        "type": "post"
		  }
	  }
  ],
	"searches": [
		"searchhash"
  ]
}

PreviousData Endpoint (CORE)NextFAQs

Last updated