Skip to content

GraphQL Search query

Jump to bottom
Scott Hale edited this page Jul 18, 2022 · 10 revisions

Before starting with the search query, read about Querying the database through Check API

The search query

search(query: String!): CheckSearch

The search query returns medias that meet the filter parameters sent as argument.

The argument should be given like a JSON string: "{\"keyword\":\"search keyword\"}"

Supported filter parameters examples

These are the parameters that can be used to filter the results.

team

The team in queries are also known as workspace on Check Web interface. Return all the items from the team sent on query. The search will return the items only if you have permission access to the team. By default the team is the current team of the person or bot who made the request.

query {
  search(query: "{\"team_id\":[\"248\"]}") {
    number_of_results
    medias {
      edges {
        node {
          title
          media {
            url
          }
        }
      }
    }
  }
}

projects

The projects in queries are also known as folders on Check Web interface. Return all the items added to the project sent on query. If more than one project ID is sent it will return the items in any of the projects.

query {
  search(query: "{\"projects\":[\"427\",\"637\"]}") {
    number_of_results
    medias {
      edges {
        node {
          title
          media {
            url
          }
        }
      }
    }
  }
}

project groups

The project group in queries are also known as collections on Check Web interface. Return all the items added to the project group sent on query. If more than one project group ID is sent it will return the items in any of the project groups.

query {
  search(query: "{\"project_group_id\":[\"133\",\"134\"]}") {
    number_of_results
    medias {
      edges {
        node {
          title
          media {
            url
          }
        }
      }
    }
  }
}

keyword

Return all the items that include the keyword sent on query. By default the keyword should be present on item's title, description, quote (when the media type is text), analysis title, analysis description, url, tags, accounts (source), task answers, metadata answers, comments or task comments to be returned on query. To search on only specific fields see keyword fields

query {
  search(query: "{\"keyword\":\"Spirited\"}") {
    number_of_results
    medias {
      edges {
        node {
          title
          media {
            url
          }
        }
      }
    }
  }
}

See the how to power your search for more information about using operators OR and AND.

keyword fields

Specify which fields should be used to match the keyword sent and in which metadata. The keyword fields accept two keys, fields and team_tasks:

  • team_tasks: should include the IDs of the metadata to search on
  • fields: can be title, description, url, analysis_title, analysis_description, tags, accounts, task_answers, metadata_answers, comments or task_comments.
query {
  search(query: "{\"keyword\":\"Spirited\",\"keyword_fields\":{\"fields\":[\"title\",\"description\"],\"team_tasks\":[\"2901\",\"7824\"]}}") {
    number_of_results
    medias {
      edges {
        node {
          title
          media {
            url
          }
        }
      }
    }
  }
}

tags

Return the items that are tagged with the strings sent on query. If more than one tag is sent, by default the search will assume the operator is an or and return the medias tagged with any of the tags. To search for items that includes all the tags listed, you must send also tags_operator with value and.

query {
  search(query: "{\"tags\": [\"movie\",\"ghibli\"],\"tags_operator\":\"and\"}") {
    number_of_results
    medias {
      edges {
        node {
          title
          media {
            url
          }
        }
      }
    }
  }
}

item status

Return the items with the status sent on query. If more than one status is sent, the search will handle them as an OR and return the items with any of the status listed.

query {
  search(query: "{\"verification_status\":[\"false\",\"not_applicable\"]}") {
    number_of_results
    medias {
      edges {
        node {
          title
          description
          media {
            url
          }
        }
      }
    }
  }
}

report status

Return the items which report status was sent on query. The status can be unpublished, paused or published. If more than one report status is sent, the search will handle them as an OR and return the items with any of the report status listed.

query {
  search(query: "{\"report_status\":[\"unpublished\",\"paused\"]}") {
    number_of_results
    medias {
      edges {
        node {
          title
          description
          media {
            url
          }
        }
      }
    }
  }
}

assignments

Return all the items assigned to the users sent on query. If more than one user ID is sent it will return the items assigned to any of the users.

query {
  search(query: "{\"assigned_to\":[\"3235\",\"50\"]}") {
    number_of_results
    medias {
      edges {
        node {
          title
          description
          media {
            url
          }
        }
      }
    }
  }
}

range

The range parameter allows searching between two dates. Currently the items can be searched by 4 criteria related to date:

  • created_at: the first time the item was added to Check
  • updated_at: when the item was updated for the last time. The items are updated when annotating, commenting, changing status...
  • last_seen: the last time the item was sent to Check
  • published_at: the time an item was published

The criteria must be sent on key range and should include the start_time and end_time to define the range.

query {
  search(query: "{\"range\":{\"created_at\":{\"start_time\":\"2021-06-17T07:00:00.000Z\",\"end_time\":\"2021-06-26T06:59:59.000Z\"}}}") {
    number_of_results
    medias {
      edges {
        node {
          title
          description
          media {
            url
          }
        }
      }
    }
  }
}

media type

Return the items of type sent on query. The type can be:

  • images: jpg, jpeg, gif or png image file
  • videos: mp4, ogg, ogv, webm, mov or m4v video file
  • claims: text
  • links: URL
  • audios: mp3, wav or ogg upload file
  • blank: imported report

If more than one media type is sent, the search will handle them as an OR and return the items with any of the types listed.

By default all media types are sent: claims, links, images, videos, audios and blank.

query {
  search(query: "{\"show\":[\"images\",\"videos\"]}") {
    number_of_results
    medias {
      edges {
        node {
          title
          description
          media {
            url
          }
        }
      }
    }
  }
}

created by

Return all the items created by the users sent on query. If more than one user ID is sent it will return the items created by to any of the users.

query {
  search(query: "{\"users\":[\"24\",\"16137\"]}") {
    number_of_results
    medias {
      edges {
        node {
          title
          description
          media {
            url
          }
        }
      }
    }
  }
}

language

Return all the items identified and the language sent on query. If more than one language code is sent it will return the items in any of the languages. Alegre Bot should be enabled to identify the languages.

query {
  search(query: "{\"dynamic\":{\"language\":[\"en\",\"pt\"]}") {
    number_of_results
    medias {
      edges {
        node {
          title
          description
          media {
            url
          }
        }
      }
    }
  }
}

source

Return all the items that have the source sent on query. If more than one source ID is sent it will return the items from any of the sources.

query {
  search(query: "{\"sources\":[\"57891\",\"57267\"]}") {
    number_of_results
    medias {
      edges {
        node {
          title
          description
          media {
            url
          }
        }
      }
    }
  }
}

team tasks

The team_tasks parameter allows searching on metadata and team tasks. The filters should be sent as an Array containing the following keys:

  • id: the ID of metadata or team task
  • response: the metadata value or task answer you are searching for. You can search for any answer, no answer or specific answer
    • ANY_VALUE: the metadata has a value or the task has an answer
    • NO_VALUE: the metadata or the task answer is blank
    • specific answer: if the metadata or task is a single or multiple choice, is one of the answer options. For example, if it's a Yes/No metadata or task, you can send Yes or No

If more than one project ID is sent it will return the items in any of the projects.

query {
  search(query: "{\"team_tasks\":[{\"id\":\"7823\",\"response\":\"NO_VALUE\"}]}") {
    number_of_results
    medias {
      edges {
        node {
          title
          description
          media {
            url
          }
        }
      }
    }
  }
}

Filters combination

The filter parameters listed here can be used together in a query. By default the search will assume the operator AND and return the items that match all the criteria. To search for items that match any of the filters as operator OR, you should include \"operator\":\"OR\"

query {
  search(query: "{\"projects\":[\"427\",\"637\"],\"keyword\":\"Spirited\",\"operator\":\"OR\"}") {
    number_of_results
    medias {
      edges {
        node {
          title
          media {
            url
          }
        }
      }
    }
  }
}

Sorting options

The query accept sort and sort_type parameters to sort the results.

sort can be:

  • comment_count: number of comments added to the item
  • demand: number of times the item was sent to Check
  • last_seen: last time the item was added
  • media_published_at: when the report was published
  • published_at: last time the item was published
  • reaction_count: number of reactions on social networks
  • recent_activity: last time the item was updated
  • recent_added: when the item was added for the first time
  • related: number of items linked where the item is the source (main)
  • related_count: number of items related where the item is source (main) or target (secondary)
  • report_status: group the items by report status and list them
  • share_count: number of times the item was shared on social netowrks
  • status_index: label of the verification status
  • suggestions_count: number of items suggested to be similar
  • tags_as_sentence: list of tags
  • type_of_media: group the items by type of media and list them
  • title: the item's title

sort_type can be:

  • asc: to show the results in ascendant order
  • desc: to show the results in descendant order

By default the sort_type is desc and sort is last_seen if tipline installed and recent_added otherwise.

query {
  search(query: "{\"keyword\":\"Spirited\",\"sort\":\"recent_added\",\"sort_type\":\"asc\"}") {
    number_of_results
    medias {
      edges {
        node {
          title
          media {
            url
          }
        }
      }
    }
  }
}

Search on similar items

The search can be performed only on main items or include the items that are marked as similar of others. The query accepts the key show_similar to enable/disable the search on similar/secondary items.

By default the key has value false and will search only on main items. To search on secondary items too you should include \"show_similar\":true

query {
  search(query: "{\"keyword\":\"Spirited\",\"show_similar\":true}") {
    number_of_results
    medias {
      edges {
        node {
          title
          media {
            url
          }
        }
      }
    }
  }
}

Results pagination

The query accepts two keys to paginate the results:

  • eslimit: limit the number of items to be returned on results
  • esoffset: the (zero-based) offset of the first item in the result to return

By default the eslimit is 50 and esoffset is 0, so the query returns 50 items starting from the first item that matches the query.

To return other amount of items you should include \"eslimit\":<number_of_items>. We advise you to use no more than the default value of 50 and use \"esoffset\":<number_of_items_to_jump> to get the items in batches.

query {
  search(query: "{\"keyword\":\"Spirited\",\"eslimit\":2,\"esoffset\":2}") {
    number_of_results
    medias {
      edges {
        node {
          title
          media {
            url
          }
        }
      }
    }
  }
}

Escaping characters on queries

The examples listed above shows the query when using a GraphQL interface to send the requests.

If you are sending the requests using a programming language or cURL you need to escape the query content. Escaping is language dependent and so you'll need to see how it works for the language you are using.

These examples show how to send the request to get the number of items (medias) of a team and the title and description of one item. Both requests will return the same data.

The first example can be used in a GraphQL interface and the second example escapes the characters to be used on a cURL request. The same escaping idea can be adapted to use the others filter parameters.

GraphQL interface

query {
  search(query: "{\"team_id\":[\"2\"],\"eslimit\":1}") {
    number_of_results
    medias {
      edges {
        node {
          title
          description
        }
      }
    }
  }
}

cURL request

curl 'https://check-api.checkmedia.org/api/graphql' \
  -H 'X-Check-Token: TOKEN' \
  -H 'X-Check-Team: <your_team_slug>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"query":"query { search(query: \"{\\\"team_id\\\":[\\\"2\\\"],\\\"eslimit\\\":1}\") { number_of_results medias { edges { node { title description } } } } }"}'

If you are using GQL (a GraphQL client for Python 3.6+) you should read Escaping special characters in JSON queries

Be sure to read the Coding Guidelines before reporting a new issue or open a pull request.

If you have questions about using Check, please create a topic on our support forum under category "Developer Support"

Check API

API Reference

Extending

Contributing

Clone this wiki locally