GraphQL APIs

If you are using NocoDB with version 0.90 onwards, please check out the latest documentation here instead. The documentation for previous versions is no longer maintained and will be completely removed on 30 Jun 2022. See v0.90 Important Announcement for more.

Features

  • Generates GraphQL APIs for ANY MySql, Postgres, MSSQL, Sqlite database :fire:
  • Serves GraphQL queries irrespective of naming conventions of primary keys, foreign keys, tables etc :fire:
  • Support for composite primary keys :fire:
  • Usual suspects : CRUD, List, FindOne, Count, Exists, Distinct
  • Pagination
  • Sorting
  • Column filtering - Fields :fire:
  • Row filtering - Where :fire:
  • Bulk insert, Bulk delete, Bulk read :fire:
  • Relations - automatically detected
  • Aggregate functions
  • More
    • Upload single file
    • Upload multiple files
    • Download file
  • Authentication
  • Access Control

API Overview

Query

ResolverArgumentsReturnsDescription
TableNameListwhere: String, limit: Int, offset: Int, sort: String[TableName]List of table rows
TableNameReadid:StringTableNameGet row by primary key
TableNameExistsid: StringBooleanCheck row exists by primary key
TableNameFindOnewhere: StringTableNameFind row by where conditions
TableNameCountwhere: StringIntGet rows count
TableNameDistinctcolumnName: String, where: String, limit: Int, offset: Int, sort: String[TableName]Get distinct rows based on provided column names
TableNameGroupByfields: String, having: String, limit: Int, offset: Int, sort: String[TableNameGroupBy]Group rows by provided columns
TableNameAggregatecolumnName: String!, having: String, limit: Int, offset: Int, sort: String, func: String![TableNameAggregate]Do aggregation based on provided column name aggregate function
TableNameDistributionmin: Int, max: Int, step: Int, steps: String, columnName: String![distribution]Get distributed list

Mutations

ResolverArgumentsReturnsDescription
TableNameCreatedata:TableNameInputTableNameInsert row into table
TableNameUpdateid:String,data:TableNameInputTableNameUpdate table row using primary key
TableNameDeleteid:StringTableNameDelete table row using primary id
TableNameCreateBulkdata: [TableNameInput][Int]Bulk row insert
TableNameUpdateBulkdata: [TableNameInput][Int]Bulk row update
TableNameDeleteBulkdata: [TableNameInput][Int]Bulk row delete

Query params

ParamDescriptionDefault valueExample Value
whereLogical Expression(colName,eq,colValue)~or(colName2,gt,colValue2)
Usage: Comparison operators
Usage: Logical operators
limitNumber of rows to get(SQL limit value)1020
offsetOffset for pagination(SQL offset value)020
sortSort column name, where use - as prefix for descending sortcolumn_name
fieldsRequired column names in result*column_name_1,column_name_2

Comparison operators

eq      -   '='         -  (colName,eq,colValue)
not     -   '!='        -  (colName,not,colValue)
gt      -   '>'         -  (colName,gt,colValue)
ge      -   '>='        -  (colName,ge,colValue)
lt      -   '<'         -  (colName,lt,colValue)
le      -   '<='        -  (colName,le,colValue)
is      -   'is'        -  (colName,is,true/false/null)
isnot   -   'is not'    -  (colName,isnot,true/false/null)
in      -   'in'        -  (colName,in,val1,val2,val3,val4)
btw     -   'between'   -  (colName,btw,val1,val2) 
nbtw    -  'not between'-  (colName,nbtw,val1,val2) 
like    -   'like'      -  (colName,like,%name)

Example use of comparison operators - complex example

PaymentList(where:"(checkNumber,eq,JM555205)~or((amount,gt,200)~and(amount,lt,2000))") 

Logical operators

~or     -   'or'
~and    -   'and'
~not    -   'not'

Examples

TableNameList

CountryList {
    country_id
    country
    last_update
}
{
  "data": {
    "CountryList": [
      {
        "country_id": 1,
        "country": "Afghanistan",
        "last_update": "1139978640000",
        "CityCount": 1
      },
      {
        "country_id": 2,
        "country": "Algeria",
        "last_update": "1139978640000",
        "CityCount": 3
      },
      {
        "country_id": 3,
        "country": "American Samoa",
        "last_update": "1139978640000",
        "CityCount": 1
      }
    ]
  }
}

List + where

{
  CountryList(where:"(country,like,United%)") {
    country_id
    country
    last_update
    CityCount
  }
}
{
  "data": {
    "CountryList": [
      {
        "country_id": 101,
        "country": "United Arab Emirates",
        "last_update": "1139958840000",
        "CityCount": 3
      },
      {
        "country_id": 102,
        "country": "United Kingdom",
        "last_update": "1139958840000",
        "CityCount": 8
      },
      {
        "country_id": 103,
        "country": "United States",
        "last_update": "1139958840000",
        "CityCount": 35
      }
    ]
  }
}

Usage : comparison operators

List + where + sort

{
  CountryList(where:"(country,like,United%)",sort:"-country") {
    country_id
    country
    last_update
    CityCount
  }
}
{
  "data": {
    "CountryList": [
      {
        "country_id": 103,
        "country": "United States",
        "last_update": "1139958840000",
        "CityCount": 35
      },
      {
        "country_id": 102,
        "country": "United Kingdom",
        "last_update": "1139958840000",
        "CityCount": 8
      },
      {
        "country_id": 101,
        "country": "United Arab Emirates",
        "last_update": "1139958840000",
        "CityCount": 3
      }
    ]
  }
}

List + where + sort + offset

{
  CountryList(where:"(country,like,United%)",sort:"-country",offset:1) {
    country_id
    country
    last_update
    CityCount
  }
}
{
  "data": {
    "CountryList": [
      {
        "country_id": 102,
        "country": "United Kingdom",
        "last_update": "1139958840000",
        "CityCount": 8
      },
      {
        "country_id": 101,
        "country": "United Arab Emirates",
        "last_update": "1139958840000",
        "CityCount": 3
      }
    ]
  }
}

List + limit

{
  CountryList(limit:6) {
    country
  }
}
{
  "data": {
    "CountryList": [
      {
        "country": "Afghanistan"
      },
      {
        "country": "Algeria"
      },
      {
        "country": "American Samoa"
      },
      {
        "country": "Angola"
      },
      {
        "country": "Anguilla"
      },
      {
        "country": "Argentina"
      }
    ]
  }
}

TableNameRead

 CountryRead(id:"1") {
   country_id
   country
   last_update
 }
  "data": {
    "CountryRead": {
      "country_id": 1,
      "country": "Afghanistan",
      "last_update": "1139978640000",
      "CityCount": 1
    }
  }

TableNameExists

 CountryExists(id:"1")
  "data": {
    "CountryExists": true
  }

TableNameFindOne

 CountryFindOne(where:"(country_id,eq,1)") {
   country_id
   country
   last_update
   CityCount
 }
  "data": {
    "CountryFindOne": {
      "country_id": 1,
      "country": "Afghanistan",
      "last_update": "1139978640000",
      "CityCount": 1
    }
  }

TableNameCount

CountryCount
{
 "data": {
    "CountryCount": 109
  }
}

TableNameDistinct

{
  CountryDistinct(columnName:"last_update",limit:3) {
    last_update
  }
}
{
  "data": {
    "CountryDistinct": [
      {
        "last_update": "1139958840000"
      },
      {
        "last_update": "1578323893000"
      },
      {
        "last_update": "1578321201000"
      }
    ]
  }
}

TableNameGroupBy

{
  CountryGroupBy(fields:"last_update",limit:1) {
    country_id
    country
    last_update
    count
  }
}
{
  "data": {
    "CountryGroupBy": [
      {
        "country_id": null,
        "country": null,
        "last_update": "1139958840000",
        "count": 109
      }
    ]
  }
}

TableNameAggregate

{
  PaymentAggregate(columnName:"amount",func:"min,max,avg,count") {
    count
    avg
    min
  }
}
{
  "data": {
    "PaymentAggregate": [
      {
        "count": 16048,
        "avg": 4.200743,
        "min": 0
      }
    ]
  }
}

TableNameDistribution

{
  PaymentDistribution (columnName:"amount"){
    range
    count
  }
}
{
  "data": {
    "PaymentDistribution": [
      {
        "range": "0-4",
        "count": 8302
      },
      {
        "range": "5-8",
        "count": 3100
      },
      {
        "range": "9-11.99",
        "count": 371
      }
    ]
  }
}

TableNameCreate

mutation {
  CountryCreate(data: {country: "test"}) {
    country_id
    country
    last_update
    CityCount
  }
}
{
  "data": {
    "CountryCreate": {
      "country_id": 10264,
      "country": "test",
      "last_update": null,
      "CityCount": 0
    }
  }
}

TableNameUpdate

mutation {
  CountryUpdate(data: {country: "test_new"}, id: "10264") {
    country_id
    country
    last_update
    CityCount
  }
}
{
  "data": {
    "CountryUpdate": {
      "country_id": null,
      "country": null,
      "last_update": null,
      "CityCount": null
    }
  }
}

TableNameDelete

mutation {
  CountryDelete(id: "10264") {
    country_id
    country
    last_update
    CityCount
  } 
}
{
  "data": {
    "CountryDelete": {
      "country_id": null,
      "country": null,
      "last_update": null,
      "CityCount": null
    }
  }
}

TableNameCreateBulk

mutation {
  CountryCreateBulk(data:[{country:"test 2"},{country:"test 3"}])
}
{
  "data": {
    "CountryCreateBulk": [
      10265
    ]
  }
}

TableNameUpdateBulk

mutation {
  CountryUpdateBulk(data: [{country: "test 2", country_id: 10265}, {country: "test 3", country_id: 10266}])
}
{
  "data": {
    "CountryUpdateBulk": [
      1,
      1
    ]
  }
}

TableNameDeleteBulk

mutation {
  CountryDeleteBulk(data: [{country_id: 10265}, {country_id: 10266}])
}
{
  "data": {
    "CountryDeleteBulk": [
      1,
      1
    ]
  }
}