Natural language

Ask natural languages questions and context aware partial questions against applications enabled for conversational analytics or a specific app to receive Insight Advisor generated responses and suggestions

Download OpenAPI spec

Returns the generated response for parsed chat queries, if no app was specified nor present in conversation context, suggests matching apps.

Facts

Rate limit Tier 2 (100 requests per minute)

Header Parameters

  • qlik-web-integration-id string

    This header is only required for external clients or mashups for QCS, this value of this property should be the id of the web integration set up for the external client/mashup

Request Body

Required
  • application/json object
    Show application/json properties
    • app object
      Show app properties
      • id string
      • name string
    • lang string

      The language to assume when parsing, specified as an ISO-639-1 code. Defaults to 'en' (English).

    • text string
      Required

      The sentence that will be parsed.

    • disableFollowups boolean

      The flag specifies whether to disable follow-up recommendations.

      default = false

    • disableNarrative boolean

      Flag that specifies whether the narratives should be generated for the user query or not.

      default = false

    • recommendationId string

      property that contains the Id of the recommendation for which the response should be generated.

    • clearEntityContext boolean

      Flag that clears the entity context.

      default = false

    • visualizationTypes array of strings

      Specify visualizationTypes for only which visualization object should be provided if enableVisualizations is set to true. For eg. ['linechart', 'barchart']

    • enableVisualizations boolean

      Flag that specifies whether visualization object should be provided or not.

      default = false

    • disableConversationContext boolean

      Flag that specifies either to enable converastion context.

      default = false

Responses

200

The sentence is not created as an app was not specified, but matching apps are suggested

  • application/json object
    Show application/json properties
    • apps array of objects
      Show apps properties
      • id string
      • name string
    • errors array of objects

      An error object.

      Show errors properties
      • code string
        Required

        The error code.

      • meta object

        Additional properties relating to the error.

      • title string
        Required

        Summary of the problem.

      • detail string

        A human-readable explanation specific to this occurrence of the problem.

      • source object

        References to the source of the error.

        Show source properties
        • pointer string

          A JSON Pointer to the property that caused the error.

        • parameter string

          The URI query parameter that caused the error.
    • nluInfo object
      Show nluInfo properties
      • elements array of objects
        Show elements properties
        • text string
        • type string
        • entity boolean
        • isFilter boolean
        • typeName string
        • errorText string
        • filterText string
        • typeTranslated string
        • filterFieldName string
    • conversationalResponse object
      Show conversationalResponse properties
      • apps array of objects
        Show apps properties
        • id string
        • name string
      • responses array of objects
        Show responses properties
        • type string
        • imageUrl string
        • infoType string
        • sentence object
          Show sentence properties
          • text string
        • narrative object
          Show narrative properties
          • text string
        • infoValues array of arrays
          One of:
          • array of strings
          • array of objects
            Show properties
            • id string
            • name string
        • errorMessage string
        • followupSentence string
        • renderVisualization object
          Show renderVisualization properties
          • data object

            Data object should be used to render visualization

          • language string
      • contextInfo string

        For contextual responses, this string contains a list of entities that are used to produce the response.

      • drillDownURI string

        The URL with the query injected to insight advisor of the app to which the query belongs.

      • sentenceWithMatches string

201

The sentence created

  • application/json object

    The attributes of sentences.

    Show application/json properties
    • apps array of objects
      Show apps properties
      • id string
      • name string
    • nluInfo object
      Show nluInfo properties
      • elements array of objects
        Show elements properties
        • text string
        • type string
        • entity boolean
        • isFilter boolean
        • typeName string
        • errorText string
        • filterText string
        • typeTranslated string
        • filterFieldName string
    • conversationalResponse array of objects

      A list of conversational responses.

      Show conversationalResponse properties
      • apps array of objects
        Show apps properties
        • id string
        • name string
      • responses array of objects
        Show responses properties
        • type string
        • imageUrl string
        • infoType string
        • sentence object
          Show sentence properties
          • text string
        • narrative object
          Show narrative properties
          • text string
        • infoValues array of arrays
          One of:
          • array of strings
          • array of objects
            Show properties
            • id string
            • name string
        • errorMessage string
        • followupSentence string
        • renderVisualization object
          Show renderVisualization properties
          • data object

            Data object should be used to render visualization

          • language string
      • contextInfo string

        For contextual responses, this string contains a list of entities that are used to produce the response.

      • drillDownURI string

        The URL with the query injected to insight advisor of the app to which the query belongs.

      • sentenceWithMatches string

400

Bad request. The payload is not formed correctly.

  • application/json object
    Show application/json properties
    • errors array of objects

      An error object.

      Show errors properties
      • code string
        Required

        The error code.

      • meta object

        Additional properties relating to the error.

      • title string
        Required

        Summary of the problem.

      • detail string

        A human-readable explanation specific to this occurrence of the problem.

      • source object

        References to the source of the error.

        Show source properties
        • pointer string

          A JSON Pointer to the property that caused the error.

        • parameter string

          The URI query parameter that caused the error.

401

User is not authorized

  • application/json object
    Show application/json properties
    • errors array of objects

      An error object.

      Show errors properties
      • code string
        Required

        The error code.

      • meta object

        Additional properties relating to the error.

      • title string
        Required

        Summary of the problem.

      • detail string

        A human-readable explanation specific to this occurrence of the problem.

      • source object

        References to the source of the error.

        Show source properties
        • pointer string

          A JSON Pointer to the property that caused the error.

        • parameter string

          The URI query parameter that caused the error.

422

Unprocessable entity. The payload contains fields that are invalid, such as too long of a query.

  • application/json object
    Show application/json properties
    • errors array of objects

      An error object.

      Show errors properties
      • code string
        Required

        The error code.

      • meta object

        Additional properties relating to the error.

      • title string
        Required

        Summary of the problem.

      • detail string

        A human-readable explanation specific to this occurrence of the problem.

      • source object

        References to the source of the error.

        Show source properties
        • pointer string

          A JSON Pointer to the property that caused the error.

        • parameter string

          The URI query parameter that caused the error.

default

Unexpected error.

  • application/json object
    Show application/json properties
    • errors array of objects

      An error object.

      Show errors properties
      • code string
        Required

        The error code.

      • meta object

        Additional properties relating to the error.

      • title string
        Required

        Summary of the problem.

      • detail string

        A human-readable explanation specific to this occurrence of the problem.

      • source object

        References to the source of the error.

        Show source properties
        • pointer string

          A JSON Pointer to the property that caused the error.

        • parameter string

          The URI query parameter that caused the error.
POST /api/v1/questions/actions/ask 
import { createQlikApi } from '@qlik/api'


const qlik = createQlikApi({
  hostConfig: {
    host: 'https://{tenant}.{region}.qlikcloud.com',
    apiKey: '<access-token>',
  },
})


await qlik.questions.askQuestions({
  app: { id: 'string', name: 'string' },
  lang: 'string',
  recommendationId: 'string',
  text: 'string',
  visualizationTypes: ['string'],
})
qlik question ask \
  --text 'string'
curl "https://{tenant}.{region}.qlikcloud.com/api/v1/questions/actions/ask" \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer <access_token>" \
-d '{"app":{"id":"string","name":"string"},"lang":"string","text":"string","disableFollowups":false,"disableNarrative":false,"recommendationId":"string","clearEntityContext":false,"visualizationTypes":["string"],"enableVisualizations":false,"disableConversationContext":false}'

Example Response

{
  "apps": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "errors": [
    {
      "code": "string",
      "meta": {},
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      }
    }
  ],
  "nluInfo": {
    "elements": [
      {
        "text": "string",
        "type": "string",
        "entity": true,
        "isFilter": true,
        "typeName": "string",
        "errorText": "string",
        "filterText": "string",
        "typeTranslated": "string",
        "filterFieldName": "string"
      }
    ]
  },
  "conversationalResponse": {
    "apps": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "responses": [
      {
        "type": "string",
        "imageUrl": "string",
        "infoType": "string",
        "sentence": {
          "text": "string"
        },
        "narrative": {
          "text": "string"
        },
        "infoValues": [
          [
            "string"
          ]
        ],
        "errorMessage": "string",
        "followupSentence": "string",
        "renderVisualization": {
          "data": {},
          "language": "string"
        }
      }
    ],
    "contextInfo": "string",
    "drillDownURI": "string",
    "sentenceWithMatches": "string"
  }
}

Returns NL metrics based on provided app IDs the user has access to.

Facts

Rate limit Tier 2 (100 requests per minute)

Query Parameters

  • limit integer

    The preferred number of entries returned

    minimum = 1, maximum = 100, default = 100, format = int32, default = 100

  • page string

    A cursor pointing to the page of data to retrieve.

  • sort string

    A single field from the data model on which to sort the response. The '+' or '-' operator may be used to specify ascending or desending order.

    Can be one of: "createdAt""updatedAt""+createdAt""+updatedAt""-createdAt""-updatedAt"

    default = "+createdAt"

Request Body

Required
  • application/json object
    Show application/json properties
    • filter string
      Required

      The advanced filtering to use for the query. Refer to RFC 7644 for the syntax.

      Filter on createdAt and updatedAt fields are encouraged and support eq, ne, gt, ge, lt, le comparison operators along with and and or logical operators.

      Filter on tenantId field is not supported.

      co, sw and ew operators are not supported.

      Examples:

      appId eq 'appId1'

      (appId eq 'appId1' or appId eq 'appId2')

      (appId eq 'appId1' or appId eq 'appId2') and (createdAt gt '2022-08-03T00:00:00.000Z' and createdAt lt '2022-08-04T00:00:00.000Z')

      (appId eq 'appId1') and (createdAt ge '2022-08-03T00:00:00.000Z')

      (appId eq 'appId1') and (createdAt le '2022-08-23:59:59.000Z')

      (appId eq 'appId1') and (questionId eq '12345')

Responses

200

If the user has access to any of the provided app id

  • application/json object
    Show application/json properties
    • data array of objects
      Show data properties
      • id string
        Required

        Unique record id stored in database

        format = "uuid"

      • apps array of objects

        Metadata for app

        Show apps properties
        • id string
        • name string
        • space_id string
        • space_name string
        • space_type string
        • limited_access boolean
        • last_reload_date string

          format = "date-time"

      • lang string

        language selected for query from insight advisor or insight advisor chat or third party api

      • appId string
        Required

        Qlik sense app id that is being used to answer the question

        format = "uuid"

      • appName string

        Qlik sense app name that is being used to answer the question

      • nluInfo array of objects

        Contains break down of the asked question in the form of tokens with their classification.

        Show nluInfo properties
        • role string

          Role of the token or phrase from query

          Can be one of: "dimension""measure""date"

        • text string

          Matching token or phrase from query

        • type string

          Type of token from query

          Can be one of: "field""filter""master_dimension""master_measure""custom_analysis"

        • fieldName string

          Qlik sense application field selected for given token or phrase

        • fieldValue string

          Filter value found from query
      • version string
        Required

        Version of the metric model

      • feedback array of objects

        Any feedback from the user about a given recommendation

        Show feedback properties
        • comment string
        • chartType string
        • analysisType string
        • recommendationLiked boolean
          Required
        • recommendationDisliked boolean
          Required
        • recommendationAddedToHub boolean
          Required
        • recommendationAddedToSheet boolean
          Required
      • tenantId string

        Qlik sense tenant Id

        format = "uuid"

      • channelId string

        Source from which conversation is happening

      • chartType string

        Chart type for given query. For insight advisor it would be 'native' and for insight advisor chat, it could be 'static' or 'responsive'

      • createdAt string
        Required Filterable

        Record created date

        format = "date-time"

      • createdBy string

        Qlik sense user id who is interacting with insight advisor or insight advisor chat or third party api

      • queryText string

        Query asked by user in insight advisor or insight advisor or third party api

      • queryType string

        Nature of query being asked during the conversation e.g. query, applist, measurelist, dimensionlist

        Can be one of: "appList""appSuggested""dimensionList""exploreThisFurther""followup""greetings""measureList""query""sampleQuestion"

      • responses object

        Provides info what was included in response for given query

        Show responses properties
        • hasChart boolean

          Chart was provided

        • hasInsights boolean

          Narrative was provided

        • hasSuggestions boolean

          Suggestion questions was provided

        • hasMetadataApps boolean

          App list was provided

        • hasSampleQueries boolean

          Sample questions was provided

        • hasMetadataMeasures boolean

          Measures list was provided

        • hasMetadataDimensions boolean

          Dimensions list was provided
      • stopWords array of strings

        Tokens from question parsed which are ignored

      • updatedAt string
        Required Filterable

        Record modified date

        format = "date-time"

      • queryError boolean

        default = false

      • questionId string
        Required

        Unique id assigned to user query

      • queryOrigin string

        Refers to source from where narrative request is called

        Can be one of: "askQuestion""iaAnalysis""iaAssetsPanel"

        default = "askQuestion"

      • recommendations array of objects

        Visualisation recommendation specs for the query

        Show recommendations properties
        • dims array of strings

          Dimension(s) considered for recommendation

        • msrs array of strings

          Measure(s) considered for recommendation

        • analysis string

          Can be one of: "breakdown""changePoint""comparison""contribution""correlation""fact""mutualInfo""rank""spike""trend""values"

        • chartType string

          Chart type given to current recommendation

          Can be one of: "barchart""combochart""distributionplot""kpi""linechart""map""scatterplot""table"

        • relevance number
        • analysisGroup string

          Can be one of: "anomaly""brekadown""comparison""correl""fact""list""mutualInfo""rank"

      • isContextualQuery boolean

        Boolean value indicates whether given query is contextual or not. It would be false for insight advisor

        default = false

      • unmatchedEntities array of strings

        Tokens parsed as entities but not matched with app's field/dimension/measure
    • meta object
      Show meta properties
      • total integer
        Required

        The total number of metrics matching the current filter.
    • links object
      Show links properties
      • next object
        Show next properties
        • href string

          format = "uri"

      • prev object
        Show prev properties
        • href string

          format = "uri"

      • self object
        Show self properties
        • href string

          format = "uri"

400

Bad request. The payload is not formed correctly.

  • application/json object
    Show application/json properties
    • errors array of objects

      An error object.

      Show errors properties
      • code string
        Required

        The error code.

      • meta object

        Additional properties relating to the error.

      • title string
        Required

        Summary of the problem.

      • detail string

        A human-readable explanation specific to this occurrence of the problem.

      • source object

        References to the source of the error.

        Show source properties
        • pointer string

          A JSON Pointer to the property that caused the error.

        • parameter string

          The URI query parameter that caused the error.

401

User is not authorized

  • application/json object
    Show application/json properties
    • errors array of objects

      An error object.

      Show errors properties
      • code string
        Required

        The error code.

      • meta object

        Additional properties relating to the error.

      • title string
        Required

        Summary of the problem.

      • detail string

        A human-readable explanation specific to this occurrence of the problem.

      • source object

        References to the source of the error.

        Show source properties
        • pointer string

          A JSON Pointer to the property that caused the error.

        • parameter string

          The URI query parameter that caused the error.

422

Unprocessable entity. The payload contains fields that are invalid, such as too long of a query.

  • application/json object
    Show application/json properties
    • errors array of objects

      An error object.

      Show errors properties
      • code string
        Required

        The error code.

      • meta object

        Additional properties relating to the error.

      • title string
        Required

        Summary of the problem.

      • detail string

        A human-readable explanation specific to this occurrence of the problem.

      • source object

        References to the source of the error.

        Show source properties
        • pointer string

          A JSON Pointer to the property that caused the error.

        • parameter string

          The URI query parameter that caused the error.

500

Internal server error

  • application/json object
    Show application/json properties
    • errors array of objects

      An error object.

      Show errors properties
      • code string
        Required

        The error code.

      • meta object

        Additional properties relating to the error.

      • title string
        Required

        Summary of the problem.

      • detail string

        A human-readable explanation specific to this occurrence of the problem.

      • source object

        References to the source of the error.

        Show source properties
        • pointer string

          A JSON Pointer to the property that caused the error.

        • parameter string

          The URI query parameter that caused the error.
POST /api/v1/questions/actions/filter 
import { createQlikApi } from '@qlik/api'


const qlik = createQlikApi({
  hostConfig: {
    host: 'https://{tenant}.{region}.qlikcloud.com',
    apiKey: '<access-token>',
  },
})


await qlik.questions.filterQuestions(
  {},
  { filter: 'string' },
)
qlik question filter \
  --filter 'string'
curl "https://{tenant}.{region}.qlikcloud.com/api/v1/questions/actions/filter" \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer <access_token>" \
-d '{"filter":"string"}'

Example Response

{
  "data": [
    {
      "id": "c35f4b70-3ce4-4a30-b62b-2aef16943bc4",
      "apps": [
        {
          "id": "string",
          "name": "string",
          "space_id": "string",
          "space_name": "string",
          "space_type": "string",
          "limited_access": true,
          "last_reload_date": "2018-10-30T07:06:22Z"
        }
      ],
      "lang": "string",
      "appId": "c35f4b70-3ce4-4a30-b62b-2aef16943bc4",
      "appName": "string",
      "nluInfo": [
        {
          "role": "dimension",
          "text": "string",
          "type": "field",
          "fieldName": "string",
          "fieldValue": "string"
        }
      ],
      "version": "string",
      "feedback": [
        {
          "comment": "string",
          "chartType": "string",
          "analysisType": "string",
          "recommendationLiked": true,
          "recommendationDisliked": true,
          "recommendationAddedToHub": true,
          "recommendationAddedToSheet": true
        }
      ],
      "tenantId": "c35f4b70-3ce4-4a30-b62b-2aef16943bc4",
      "channelId": "string",
      "chartType": "string",
      "createdAt": "2018-10-30T07:06:22Z",
      "createdBy": "string",
      "queryText": "string",
      "queryType": "appList",
      "responses": {
        "hasChart": true,
        "hasInsights": true,
        "hasSuggestions": true,
        "hasMetadataApps": true,
        "hasSampleQueries": true,
        "hasMetadataMeasures": true,
        "hasMetadataDimensions": true
      },
      "stopWords": [
        "string"
      ],
      "updatedAt": "2018-10-30T07:06:22Z",
      "queryError": false,
      "questionId": "string",
      "queryOrigin": "askQuestion",
      "recommendations": [
        {
          "dims": [
            "string"
          ],
          "msrs": [
            "string"
          ],
          "analysis": "breakdown",
          "chartType": "barchart",
          "relevance": 42,
          "analysisGroup": "anomaly"
        }
      ],
      "isContextualQuery": false,
      "unmatchedEntities": [
        "string"
      ]
    }
  ],
  "meta": {
    "total": 42
  },
  "links": {
    "next": {
      "href": "http://example.com"
    },
    "prev": {
      "href": "http://example.com"
    },
    "self": {
      "href": "http://example.com"
    }
  }
}