RESTful API

This page lists the major RESTful APIs provided by Kylin.

Authentication

POST /kylin/api/user/authentication

Request Header

Authorization data encoded by basic auth is needed in the header, such as:
Authorization:Basic {data}

Response Body

  • userDetails - Defined authorities and status of current user.

Response Sample

  1. {  
  2.    "userDetails":{  
  3.       "password":null,
  4.       "username":"sample",
  5.       "authorities":[  
  6.          {  
  7.             "authority":"ROLE_ANALYST"
  8.          },
  9.          {  
  10.             "authority":"ROLE_MODELER"
  11.          }
  12.       ],
  13.       "accountNonExpired":true,
  14.       "accountNonLocked":true,
  15.       "credentialsNonExpired":true,
  16.       "enabled":true
  17.    }
  18. }

Curl Example

  1. curl -c /path/to/cookiefile.txt -X POST -H "Authorization: Basic XXXXXXXXX" -H 'Content-Type: application/json' http://<host>:<port>/kylin/api/user/authentication

If login successfully, the JSESSIONID will be saved into the cookie file; In the subsequent http requests, attach the cookie, for example:

  1. curl -b /path/to/cookiefile.txt -X PUT -H 'Content-Type: application/json' -d '{"startTime":'1423526400000', "endTime":'1423612800000', "buildType":"BUILD"}' http://<host>:<port>/kylin/api/cubes/your_cube/build

Alternatively, you can provide the username/password with option “user” in each curl call; please note this has the risk of password leak in shell history:

  1. curl -X PUT --user ADMIN:KYLIN -H "Content-Type: application/json;charset=utf-8" -d '{ "startTime": 820454400000, "endTime": 821318400000, "buildType": "BUILD"}' http://localhost:7070/kylin/api/cubes/kylin_sales/build

Query

POST /kylin/api/query

Request Body

  • sql - required string The text of sql statement.
  • offset - optional int Query offset. If offset is set in sql, curIndex will be ignored.
  • limit - optional int Query limit. If limit is set in sql, perPage will be ignored.
  • acceptPartial - optional bool Whether accept a partial result or not, default be “false”. Set to “false” for production use.
  • project - optional string Project to perform query. Default value is ‘DEFAULT’.

Request Sample

  1. {  
  2.    "sql":"select * from TEST_KYLIN_FACT",
  3.    "offset":0,
  4.    "limit":50000,
  5.    "acceptPartial":false,
  6.    "project":"DEFAULT"
  7. }

Curl Example

  1. curl -X POST -H "Authorization: Basic XXXXXXXXX" -H "Content-Type: application/json" -d '{ "sql":"select count(*) from TEST_KYLIN_FACT", "project":"learn_kylin" }' http://localhost:7070/kylin/api/query

Response Body

  • columnMetas - Column metadata information of result set.
  • results - Data set of result.
  • cube - Cube used for this query.
  • affectedRowCount - Count of affected row by this sql statement.
  • isException - Whether this response is an exception.
  • ExceptionMessage - Message content of the exception.
  • Duration - Time cost of this query
  • Partial - Whether the response is a partial result or not. Decided by acceptPartial of request.

Response Sample

  1. {  
  2.    "columnMetas":[  
  3.       {  
  4.          "isNullable":1,
  5.          "displaySize":0,
  6.          "label":"CAL_DT",
  7.          "name":"CAL_DT",
  8.          "schemaName":null,
  9.          "catelogName":null,
  10.          "tableName":null,
  11.          "precision":0,
  12.          "scale":0,
  13.          "columnType":91,
  14.          "columnTypeName":"DATE",
  15.          "readOnly":true,
  16.          "writable":false,
  17.          "caseSensitive":true,
  18.          "searchable":false,
  19.          "currency":false,
  20.          "signed":true,
  21.          "autoIncrement":false,
  22.          "definitelyWritable":false
  23.       },
  24.       {  
  25.          "isNullable":1,
  26.          "displaySize":10,
  27.          "label":"LEAF_CATEG_ID",
  28.          "name":"LEAF_CATEG_ID",
  29.          "schemaName":null,
  30.          "catelogName":null,
  31.          "tableName":null,
  32.          "precision":10,
  33.          "scale":0,
  34.          "columnType":4,
  35.          "columnTypeName":"INTEGER",
  36.          "readOnly":true,
  37.          "writable":false,
  38.          "caseSensitive":true,
  39.          "searchable":false,
  40.          "currency":false,
  41.          "signed":true,
  42.          "autoIncrement":false,
  43.          "definitelyWritable":false
  44.       }
  45.    ],
  46.    "results":[  
  47.       [  
  48.          "2013-08-07",
  49.          "32996",
  50.          "15",
  51.          "15",
  52.          "Auction",
  53.          "10000000",
  54.          "49.048952730908745",
  55.          "49.048952730908745",
  56.          "49.048952730908745",
  57.          "1"
  58.       ],
  59.       [  
  60.          "2013-08-07",
  61.          "43398",
  62.          "0",
  63.          "14",
  64.          "ABIN",
  65.          "10000633",
  66.          "85.78317064220418",
  67.          "85.78317064220418",
  68.          "85.78317064220418",
  69.          "1"
  70.       ]
  71.    ],
  72.    "cube":"test_kylin_cube_with_slr_desc",
  73.    "affectedRowCount":0,
  74.    "isException":false,
  75.    "exceptionMessage":null,
  76.    "duration":3451,
  77.    "partial":false
  78. }

List queryable tables

GET /kylin/api/tables_and_columns

Request Parameters

  • project - required string The project to load tables

Response Sample

  1. [  
  2.    {  
  3.       "columns":[  
  4.          {  
  5.             "table_NAME":"TEST_CAL_DT",
  6.             "table_SCHEM":"EDW",
  7.             "column_NAME":"CAL_DT",
  8.             "data_TYPE":91,
  9.             "nullable":1,
  10.             "column_SIZE":-1,
  11.             "buffer_LENGTH":-1,
  12.             "decimal_DIGITS":0,
  13.             "num_PREC_RADIX":10,
  14.             "column_DEF":null,
  15.             "sql_DATA_TYPE":-1,
  16.             "sql_DATETIME_SUB":-1,
  17.             "char_OCTET_LENGTH":-1,
  18.             "ordinal_POSITION":1,
  19.             "is_NULLABLE":"YES",
  20.             "scope_CATLOG":null,
  21.             "scope_SCHEMA":null,
  22.             "scope_TABLE":null,
  23.             "source_DATA_TYPE":-1,
  24.             "iS_AUTOINCREMENT":null,
  25.             "table_CAT":"defaultCatalog",
  26.             "remarks":null,
  27.             "type_NAME":"DATE"
  28.          },
  29.          {  
  30.             "table_NAME":"TEST_CAL_DT",
  31.             "table_SCHEM":"EDW",
  32.             "column_NAME":"WEEK_BEG_DT",
  33.             "data_TYPE":91,
  34.             "nullable":1,
  35.             "column_SIZE":-1,
  36.             "buffer_LENGTH":-1,
  37.             "decimal_DIGITS":0,
  38.             "num_PREC_RADIX":10,
  39.             "column_DEF":null,
  40.             "sql_DATA_TYPE":-1,
  41.             "sql_DATETIME_SUB":-1,
  42.             "char_OCTET_LENGTH":-1,
  43.             "ordinal_POSITION":2,
  44.             "is_NULLABLE":"YES",
  45.             "scope_CATLOG":null,
  46.             "scope_SCHEMA":null,
  47.             "scope_TABLE":null,
  48.             "source_DATA_TYPE":-1,
  49.             "iS_AUTOINCREMENT":null,
  50.             "table_CAT":"defaultCatalog",
  51.             "remarks":null,
  52.             "type_NAME":"DATE"
  53.          }
  54.       ],
  55.       "table_NAME":"TEST_CAL_DT",
  56.       "table_SCHEM":"EDW",
  57.       "ref_GENERATION":null,
  58.       "self_REFERENCING_COL_NAME":null,
  59.       "type_SCHEM":null,
  60.       "table_TYPE":"TABLE",
  61.       "table_CAT":"defaultCatalog",
  62.       "remarks":null,
  63.       "type_CAT":null,
  64.       "type_NAME":null
  65.    }
  66. ]

List cubes

GET /kylin/api/cubes

Request Parameters

  • offset - required int Offset used by pagination
  • limit - required int Cubes per page.
  • cubeName - optional string Keyword for cube names. To find cubes whose name contains this keyword.
  • projectName - optional string Project name.

Response Sample

  1. [  
  2.    {  
  3.       "uuid":"1eaca32a-a33e-4b69-83dd-0bb8b1f8c53b",
  4.       "last_modified":1407831634847,
  5.       "name":"test_kylin_cube_with_slr_empty",
  6.       "owner":null,
  7.       "version":null,
  8.       "descriptor":"test_kylin_cube_with_slr_desc",
  9.       "cost":50,
  10.       "status":"DISABLED",
  11.       "segments":[  
  12.       ],
  13.       "create_time":null,
  14.       "source_records_count":0,
  15.       "source_records_size":0,
  16.       "size_kb":0
  17.    }
  18. ]

Get cube

GET /kylin/api/cubes/{cubeName}

Path Variable

  • cubeName - required string Cube name to find.

Get cube descriptor

GET /kylin/api/cube_desc/{cubeName}
Get descriptor for specified cube instance.

Path Variable

  • cubeName - required string Cube name.

Response Sample

  1. [
  2.     {
  3.         "uuid": "a24ca905-1fc6-4f67-985c-38fa5aeafd92", 
  4.         "name": "test_kylin_cube_with_slr_desc", 
  5.         "description": null, 
  6.         "dimensions": [
  7.             {
  8.                 "id": 0, 
  9.                 "name": "CAL_DT", 
  10.                 "table": "EDW.TEST_CAL_DT", 
  11.                 "column": null, 
  12.                 "derived": [
  13.                     "WEEK_BEG_DT"
  14.                 ], 
  15.                 "hierarchy": false
  16.             }, 
  17.             {
  18.                 "id": 1, 
  19.                 "name": "CATEGORY", 
  20.                 "table": "DEFAULT.TEST_CATEGORY_GROUPINGS", 
  21.                 "column": null, 
  22.                 "derived": [
  23.                     "USER_DEFINED_FIELD1", 
  24.                     "USER_DEFINED_FIELD3", 
  25.                     "UPD_DATE", 
  26.                     "UPD_USER"
  27.                 ], 
  28.                 "hierarchy": false
  29.             }, 
  30.             {
  31.                 "id": 2, 
  32.                 "name": "CATEGORY_HIERARCHY", 
  33.                 "table": "DEFAULT.TEST_CATEGORY_GROUPINGS", 
  34.                 "column": [
  35.                     "META_CATEG_NAME", 
  36.                     "CATEG_LVL2_NAME", 
  37.                     "CATEG_LVL3_NAME"
  38.                 ], 
  39.                 "derived": null, 
  40.                 "hierarchy": true
  41.             }, 
  42.             {
  43.                 "id": 3, 
  44.                 "name": "LSTG_FORMAT_NAME", 
  45.                 "table": "DEFAULT.TEST_KYLIN_FACT", 
  46.                 "column": [
  47.                     "LSTG_FORMAT_NAME"
  48.                 ], 
  49.                 "derived": null, 
  50.                 "hierarchy": false
  51.             }, 
  52.             {
  53.                 "id": 4, 
  54.                 "name": "SITE_ID", 
  55.                 "table": "EDW.TEST_SITES", 
  56.                 "column": null, 
  57.                 "derived": [
  58.                     "SITE_NAME", 
  59.                     "CRE_USER"
  60.                 ], 
  61.                 "hierarchy": false
  62.             }, 
  63.             {
  64.                 "id": 5, 
  65.                 "name": "SELLER_TYPE_CD", 
  66.                 "table": "EDW.TEST_SELLER_TYPE_DIM", 
  67.                 "column": null, 
  68.                 "derived": [
  69.                     "SELLER_TYPE_DESC"
  70.                 ], 
  71.                 "hierarchy": false
  72.             }, 
  73.             {
  74.                 "id": 6, 
  75.                 "name": "SELLER_ID", 
  76.                 "table": "DEFAULT.TEST_KYLIN_FACT", 
  77.                 "column": [
  78.                     "SELLER_ID"
  79.                 ], 
  80.                 "derived": null, 
  81.                 "hierarchy": false
  82.             }
  83.         ], 
  84.         "measures": [
  85.             {
  86.                 "id": 1, 
  87.                 "name": "GMV_SUM", 
  88.                 "function": {
  89.                     "expression": "SUM", 
  90.                     "parameter": {
  91.                         "type": "column", 
  92.                         "value": "PRICE", 
  93.                         "next_parameter": null
  94.                     }, 
  95.                     "returntype": "decimal(19,4)"
  96.                 }, 
  97.                 "dependent_measure_ref": null
  98.             }, 
  99.             {
  100.                 "id": 2, 
  101.                 "name": "GMV_MIN", 
  102.                 "function": {
  103.                     "expression": "MIN", 
  104.                     "parameter": {
  105.                         "type": "column", 
  106.                         "value": "PRICE", 
  107.                         "next_parameter": null
  108.                     }, 
  109.                     "returntype": "decimal(19,4)"
  110.                 }, 
  111.                 "dependent_measure_ref": null
  112.             }, 
  113.             {
  114.                 "id": 3, 
  115.                 "name": "GMV_MAX", 
  116.                 "function": {
  117.                     "expression": "MAX", 
  118.                     "parameter": {
  119.                         "type": "column", 
  120.                         "value": "PRICE", 
  121.                         "next_parameter": null
  122.                     }, 
  123.                     "returntype": "decimal(19,4)"
  124.                 }, 
  125.                 "dependent_measure_ref": null
  126.             }, 
  127.             {
  128.                 "id": 4, 
  129.                 "name": "TRANS_CNT", 
  130.                 "function": {
  131.                     "expression": "COUNT", 
  132.                     "parameter": {
  133.                         "type": "constant", 
  134.                         "value": "1", 
  135.                         "next_parameter": null
  136.                     }, 
  137.                     "returntype": "bigint"
  138.                 }, 
  139.                 "dependent_measure_ref": null
  140.             }, 
  141.             {
  142.                 "id": 5, 
  143.                 "name": "ITEM_COUNT_SUM", 
  144.                 "function": {
  145.                     "expression": "SUM", 
  146.                     "parameter": {
  147.                         "type": "column", 
  148.                         "value": "ITEM_COUNT", 
  149.                         "next_parameter": null
  150.                     }, 
  151.                     "returntype": "bigint"
  152.                 }, 
  153.                 "dependent_measure_ref": null
  154.             }
  155.         ], 
  156.         "rowkey": {
  157.             "rowkey_columns": [
  158.                 {
  159.                     "column": "SELLER_ID", 
  160.                     "length": 18, 
  161.                     "dictionary": null, 
  162.                     "mandatory": true
  163.                 }, 
  164.                 {
  165.                     "column": "CAL_DT", 
  166.                     "length": 0, 
  167.                     "dictionary": "true", 
  168.                     "mandatory": false
  169.                 }, 
  170.                 {
  171.                     "column": "LEAF_CATEG_ID", 
  172.                     "length": 0, 
  173.                     "dictionary": "true", 
  174.                     "mandatory": false
  175.                 }, 
  176.                 {
  177.                     "column": "META_CATEG_NAME", 
  178.                     "length": 0, 
  179.                     "dictionary": "true", 
  180.                     "mandatory": false
  181.                 }, 
  182.                 {
  183.                     "column": "CATEG_LVL2_NAME", 
  184.                     "length": 0, 
  185.                     "dictionary": "true", 
  186.                     "mandatory": false
  187.                 }, 
  188.                 {
  189.                     "column": "CATEG_LVL3_NAME", 
  190.                     "length": 0, 
  191.                     "dictionary": "true", 
  192.                     "mandatory": false
  193.                 }, 
  194.                 {
  195.                     "column": "LSTG_FORMAT_NAME", 
  196.                     "length": 12, 
  197.                     "dictionary": null, 
  198.                     "mandatory": false
  199.                 }, 
  200.                 {
  201.                     "column": "LSTG_SITE_ID", 
  202.                     "length": 0, 
  203.                     "dictionary": "true", 
  204.                     "mandatory": false
  205.                 }, 
  206.                 {
  207.                     "column": "SLR_SEGMENT_CD", 
  208.                     "length": 0, 
  209.                     "dictionary": "true", 
  210.                     "mandatory": false
  211.                 }
  212.             ], 
  213.             "aggregation_groups": [
  214.                 [
  215.                     "LEAF_CATEG_ID", 
  216.                     "META_CATEG_NAME", 
  217.                     "CATEG_LVL2_NAME", 
  218.                     "CATEG_LVL3_NAME", 
  219.                     "CAL_DT"
  220.                 ]
  221.             ]
  222.         }, 
  223.         "signature": "lsLAl2jL62ZApmOLZqWU3g==", 
  224.         "last_modified": 1445850327000, 
  225.         "model_name": "test_kylin_with_slr_model_desc", 
  226.         "null_string": null, 
  227.         "hbase_mapping": {
  228.             "column_family": [
  229.                 {
  230.                     "name": "F1", 
  231.                     "columns": [
  232.                         {
  233.                             "qualifier": "M", 
  234.                             "measure_refs": [
  235.                                 "GMV_SUM", 
  236.                                 "GMV_MIN", 
  237.                                 "GMV_MAX", 
  238.                                 "TRANS_CNT", 
  239.                                 "ITEM_COUNT_SUM"
  240.                             ]
  241.                         }
  242.                     ]
  243.                 }
  244.             ]
  245.         }, 
  246.         "notify_list": null, 
  247.         "auto_merge_time_ranges": null, 
  248.         "retention_range": 0
  249.     }
  250. ]

Get data model

GET /kylin/api/model/{modelName}

Path Variable

  • modelName - required string Data model name, by default it should be the same with cube name.

Response Sample

  1. {
  2.     "uuid": "ff527b94-f860-44c3-8452-93b17774c647", 
  3.     "name": "test_kylin_with_slr_model_desc", 
  4.     "lookups": [
  5.         {
  6.             "table": "EDW.TEST_CAL_DT", 
  7.             "join": {
  8.                 "type": "inner", 
  9.                 "primary_key": [
  10.                     "CAL_DT"
  11.                 ], 
  12.                 "foreign_key": [
  13.                     "CAL_DT"
  14.                 ]
  15.             }
  16.         }, 
  17.         {
  18.             "table": "DEFAULT.TEST_CATEGORY_GROUPINGS", 
  19.             "join": {
  20.                 "type": "inner", 
  21.                 "primary_key": [
  22.                     "LEAF_CATEG_ID", 
  23.                     "SITE_ID"
  24.                 ], 
  25.                 "foreign_key": [
  26.                     "LEAF_CATEG_ID", 
  27.                     "LSTG_SITE_ID"
  28.                 ]
  29.             }
  30.         }
  31.     ], 
  32.     "capacity": "MEDIUM", 
  33.     "last_modified": 1442372116000, 
  34.     "fact_table": "DEFAULT.TEST_KYLIN_FACT", 
  35.     "filter_condition": null, 
  36.     "partition_desc": {
  37.         "partition_date_column": "DEFAULT.TEST_KYLIN_FACT.CAL_DT", 
  38.         "partition_date_start": 0, 
  39.         "partition_date_format": "yyyy-MM-dd", 
  40.         "partition_type": "APPEND", 
  41.         "partition_condition_builder": "org.apache.kylin.metadata.model.PartitionDesc$DefaultPartitionConditionBuilder"
  42.     }
  43. }

Build cube

PUT /kylin/api/cubes/{cubeName}/build

Path Variable

  • cubeName - required string Cube name.

Request Body

  • startTime - required long Start timestamp of data to build, e.g. 1388563200000 for 2014-1-1
  • endTime - required long End timestamp of data to build
  • buildType - required string Supported build type: ‘BUILD’, ‘MERGE’, ‘REFRESH’

Curl Example

  1. curl -X PUT -H "Authorization: Basic XXXXXXXXX" -H 'Content-Type: application/json' -d '{"startTime":'1423526400000', "endTime":'1423612800000', "buildType":"BUILD"}' http://<host>:<port>/kylin/api/cubes/{cubeName}/build

Response Sample

  1. {  
  2.    "uuid":"c143e0e4-ac5f-434d-acf3-46b0d15e3dc6",
  3.    "last_modified":1407908916705,
  4.    "name":"test_kylin_cube_with_slr_empty - 19700101000000_20140731160000 - BUILD - PDT 2014-08-12 22:48:36",
  5.    "type":"BUILD",
  6.    "duration":0,
  7.    "related_cube":"test_kylin_cube_with_slr_empty",
  8.    "related_segment":"19700101000000_20140731160000",
  9.    "exec_start_time":0,
  10.    "exec_end_time":0,
  11.    "mr_waiting":0,
  12.    "steps":[  
  13.       {  
  14.          "interruptCmd":null,
  15.          "name":"Create Intermediate Flat Hive Table",
  16.          "sequence_id":0,
  17.          "exec_cmd":"hive -e \"DROP TABLE IF EXISTS kylin_intermediate_test_kylin_cube_with_slr_desc_19700101000000_20140731160000_c143e0e4_ac5f_434d_acf3_46b0d15e3dc6;\nCREATE EXTERNAL TABLE IF NOT EXISTS kylin_intermediate_test_kylin_cube_with_slr_desc_19700101000000_20140731160000_c143e0e4_ac5f_434d_acf3_46b0d15e3dc6\n(\nCAL_DT date\n,LEAF_CATEG_ID int\n,LSTG_SITE_ID int\n,META_CATEG_NAME string\n,CATEG_LVL2_NAME string\n,CATEG_LVL3_NAME string\n,LSTG_FORMAT_NAME string\n,SLR_SEGMENT_CD smallint\n,SELLER_ID bigint\n,PRICE decimal\n)\nROW FORMAT DELIMITED FIELDS TERMINATED BY '\\177'\nSTORED AS SEQUENCEFILE\nLOCATION '/tmp/kylin-c143e0e4-ac5f-434d-acf3-46b0d15e3dc6/kylin_intermediate_test_kylin_cube_with_slr_desc_19700101000000_20140731160000_c143e0e4_ac5f_434d_acf3_46b0d15e3dc6';\nSET mapreduce.job.split.metainfo.maxsize=-1;\nSET mapred.compress.map.output=true;\nSET mapred.map.output.compression.codec=com.hadoop.compression.lzo.LzoCodec;\nSET mapred.output.compress=true;\nSET mapred.output.compression.codec=com.hadoop.compression.lzo.LzoCodec;\nSET mapred.output.compression.type=BLOCK;\nSET mapreduce.job.max.split.locations=2000;\nSET hive.exec.compress.output=true;\nSET hive.auto.convert.join.noconditionaltask = true;\nSET hive.auto.convert.join.noconditionaltask.size = 300000000;\nINSERT OVERWRITE TABLE kylin_intermediate_test_kylin_cube_with_slr_desc_19700101000000_20140731160000_c143e0e4_ac5f_434d_acf3_46b0d15e3dc6\nSELECT\nTEST_KYLIN_FACT.CAL_DT\n,TEST_KYLIN_FACT.LEAF_CATEG_ID\n,TEST_KYLIN_FACT.LSTG_SITE_ID\n,TEST_CATEGORY_GROUPINGS.META_CATEG_NAME\n,TEST_CATEGORY_GROUPINGS.CATEG_LVL2_NAME\n,TEST_CATEGORY_GROUPINGS.CATEG_LVL3_NAME\n,TEST_KYLIN_FACT.LSTG_FORMAT_NAME\n,TEST_KYLIN_FACT.SLR_SEGMENT_CD\n,TEST_KYLIN_FACT.SELLER_ID\n,TEST_KYLIN_FACT.PRICE\nFROM TEST_KYLIN_FACT\nINNER JOIN TEST_CAL_DT\nON TEST_KYLIN_FACT.CAL_DT = TEST_CAL_DT.CAL_DT\nINNER JOIN TEST_CATEGORY_GROUPINGS\nON TEST_KYLIN_FACT.LEAF_CATEG_ID = TEST_CATEGORY_GROUPINGS.LEAF_CATEG_ID AND TEST_KYLIN_FACT.LSTG_SITE_ID = TEST_CATEGORY_GROUPINGS.SITE_ID\nINNER JOIN TEST_SITES\nON TEST_KYLIN_FACT.LSTG_SITE_ID = TEST_SITES.SITE_ID\nINNER JOIN TEST_SELLER_TYPE_DIM\nON TEST_KYLIN_FACT.SLR_SEGMENT_CD = TEST_SELLER_TYPE_DIM.SELLER_TYPE_CD\nWHERE (test_kylin_fact.cal_dt < '2014-07-31 16:00:00')\n;\n\"",
  18.          "interrupt_cmd":null,
  19.          "exec_start_time":0,
  20.          "exec_end_time":0,
  21.          "exec_wait_time":0,
  22.          "step_status":"PENDING",
  23.          "cmd_type":"SHELL_CMD_HADOOP",
  24.          "info":null,
  25.          "run_async":false
  26.       },
  27.       {  
  28.          "interruptCmd":null,
  29.          "name":"Extract Fact Table Distinct Columns",
  30.          "sequence_id":1,
  31.          "exec_cmd":" -conf C:/kylin/Kylin/server/src/main/resources/hadoop_job_conf_medium.xml -cubename test_kylin_cube_with_slr_empty -input /tmp/kylin-c143e0e4-ac5f-434d-acf3-46b0d15e3dc6/kylin_intermediate_test_kylin_cube_with_slr_desc_19700101000000_20140731160000_c143e0e4_ac5f_434d_acf3_46b0d15e3dc6 -output /tmp/kylin-c143e0e4-ac5f-434d-acf3-46b0d15e3dc6/test_kylin_cube_with_slr_empty/fact_distinct_columns -jobname Kylin_Fact_Distinct_Columns_test_kylin_cube_with_slr_empty_Step_1",
  32.          "interrupt_cmd":null,
  33.          "exec_start_time":0,
  34.          "exec_end_time":0,
  35.          "exec_wait_time":0,
  36.          "step_status":"PENDING",
  37.          "cmd_type":"JAVA_CMD_HADOOP_FACTDISTINCT",
  38.          "info":null,
  39.          "run_async":true
  40.       },
  41.       {  
  42.          "interruptCmd":null,
  43.          "name":"Load HFile to HBase Table",
  44.          "sequence_id":12,
  45.          "exec_cmd":" -input /tmp/kylin-c143e0e4-ac5f-434d-acf3-46b0d15e3dc6/test_kylin_cube_with_slr_empty/hfile/ -htablename KYLIN-CUBE-TEST_KYLIN_CUBE_WITH_SLR_EMPTY-19700101000000_20140731160000_11BB4326-5975-4358-804C-70D53642E03A -cubename test_kylin_cube_with_slr_empty",
  46.          "interrupt_cmd":null,
  47.          "exec_start_time":0,
  48.          "exec_end_time":0,
  49.          "exec_wait_time":0,
  50.          "step_status":"PENDING",
  51.          "cmd_type":"JAVA_CMD_HADOOP_NO_MR_BULKLOAD",
  52.          "info":null,
  53.          "run_async":false
  54.       }
  55.    ],
  56.    "job_status":"PENDING",
  57.    "progress":0.0
  58. }

Enable Cube

PUT /kylin/api/cubes/{cubeName}/enable

Path variable

  • cubeName - required string Cube name.

Response Sample

  1. {  
  2.    "uuid":"1eaca32a-a33e-4b69-83dd-0bb8b1f8c53b",
  3.    "last_modified":1407909046305,
  4.    "name":"test_kylin_cube_with_slr_ready",
  5.    "owner":null,
  6.    "version":null,
  7.    "descriptor":"test_kylin_cube_with_slr_desc",
  8.    "cost":50,
  9.    "status":"ACTIVE",
  10.    "segments":[  
  11.       {  
  12.          "name":"19700101000000_20140531160000",
  13.          "storage_location_identifier":"KYLIN-CUBE-TEST_KYLIN_CUBE_WITH_SLR_READY-19700101000000_20140531160000_BF043D2D-9A4A-45E9-AA59-5A17D3F34A50",
  14.          "date_range_start":0,
  15.          "date_range_end":1401552000000,
  16.          "status":"READY",
  17.          "size_kb":4758,
  18.          "source_records":6000,
  19.          "source_records_size":620356,
  20.          "last_build_time":1407832663227,
  21.          "last_build_job_id":"2c7a2b63-b052-4a51-8b09-0c24b5792cda",
  22.          "binary_signature":null,
  23.          "dictionaries":{  
  24.             "TEST_CATEGORY_GROUPINGS/CATEG_LVL2_NAME":"/dict/TEST_CATEGORY_GROUPINGS/CATEG_LVL2_NAME/16d8185c-ee6b-4f8c-a919-756d9809f937.dict",
  25.             "TEST_KYLIN_FACT/LSTG_SITE_ID":"/dict/TEST_SITES/SITE_ID/0bec6bb3-1b0d-469c-8289-b8c4ca5d5001.dict",
  26.             "TEST_KYLIN_FACT/SLR_SEGMENT_CD":"/dict/TEST_SELLER_TYPE_DIM/SELLER_TYPE_CD/0c5d77ec-316b-47e0-ba9a-0616be890ad6.dict",
  27.             "TEST_KYLIN_FACT/CAL_DT":"/dict/PREDEFINED/date(yyyy-mm-dd)/64ac4f82-f2af-476e-85b9-f0805001014e.dict",
  28.             "TEST_CATEGORY_GROUPINGS/CATEG_LVL3_NAME":"/dict/TEST_CATEGORY_GROUPINGS/CATEG_LVL3_NAME/270fbfb0-281c-4602-8413-2970a7439c47.dict",
  29.             "TEST_KYLIN_FACT/LEAF_CATEG_ID":"/dict/TEST_CATEGORY_GROUPINGS/LEAF_CATEG_ID/2602386c-debb-4968-8d2f-b52b8215e385.dict",
  30.             "TEST_CATEGORY_GROUPINGS/META_CATEG_NAME":"/dict/TEST_CATEGORY_GROUPINGS/META_CATEG_NAME/0410d2c4-4686-40bc-ba14-170042a2de94.dict"
  31.          },
  32.          "snapshots":{  
  33.             "TEST_CAL_DT":"/table_snapshot/TEST_CAL_DT.csv/8f7cfc8a-020d-4019-b419-3c6deb0ffaa0.snapshot",
  34.             "TEST_SELLER_TYPE_DIM":"/table_snapshot/TEST_SELLER_TYPE_DIM.csv/c60fd05e-ac94-4016-9255-96521b273b81.snapshot",
  35.             "TEST_CATEGORY_GROUPINGS":"/table_snapshot/TEST_CATEGORY_GROUPINGS.csv/363f4a59-b725-4459-826d-3188bde6a971.snapshot",
  36.             "TEST_SITES":"/table_snapshot/TEST_SITES.csv/78e0aecc-3ec6-4406-b86e-bac4b10ea63b.snapshot"
  37.          }
  38.       }
  39.    ],
  40.    "create_time":null,
  41.    "source_records_count":6000,
  42.    "source_records_size":0,
  43.    "size_kb":4758
  44. }

Disable Cube

PUT /kylin/api/cubes/{cubeName}/disable

Path variable

  • cubeName - required string Cube name.

Response Sample

(Same as “Enable Cube”)

Purge Cube

PUT /kylin/api/cubes/{cubeName}/purge

Path variable

  • cubeName - required string Cube name.

Response Sample

(Same as “Enable Cube”)

Delete Segment

DELETE /kylin/api/cubes/{cubeName}/segs/{segmentName}

Resume Job

PUT /kylin/api/jobs/{jobId}/resume

Path variable

  • jobId - required string Job id.

Response Sample

  1. {  
  2.    "uuid":"c143e0e4-ac5f-434d-acf3-46b0d15e3dc6",
  3.    "last_modified":1407908916705,
  4.    "name":"test_kylin_cube_with_slr_empty - 19700101000000_20140731160000 - BUILD - PDT 2014-08-12 22:48:36",
  5.    "type":"BUILD",
  6.    "duration":0,
  7.    "related_cube":"test_kylin_cube_with_slr_empty",
  8.    "related_segment":"19700101000000_20140731160000",
  9.    "exec_start_time":0,
  10.    "exec_end_time":0,
  11.    "mr_waiting":0,
  12.    "steps":[  
  13.       {  
  14.          "interruptCmd":null,
  15.          "name":"Create Intermediate Flat Hive Table",
  16.          "sequence_id":0,
  17.          "exec_cmd":"hive -e \"DROP TABLE IF EXISTS kylin_intermediate_test_kylin_cube_with_slr_desc_19700101000000_20140731160000_c143e0e4_ac5f_434d_acf3_46b0d15e3dc6;\nCREATE EXTERNAL TABLE IF NOT EXISTS kylin_intermediate_test_kylin_cube_with_slr_desc_19700101000000_20140731160000_c143e0e4_ac5f_434d_acf3_46b0d15e3dc6\n(\nCAL_DT date\n,LEAF_CATEG_ID int\n,LSTG_SITE_ID int\n,META_CATEG_NAME string\n,CATEG_LVL2_NAME string\n,CATEG_LVL3_NAME string\n,LSTG_FORMAT_NAME string\n,SLR_SEGMENT_CD smallint\n,SELLER_ID bigint\n,PRICE decimal\n)\nROW FORMAT DELIMITED FIELDS TERMINATED BY '\\177'\nSTORED AS SEQUENCEFILE\nLOCATION '/tmp/kylin-c143e0e4-ac5f-434d-acf3-46b0d15e3dc6/kylin_intermediate_test_kylin_cube_with_slr_desc_19700101000000_20140731160000_c143e0e4_ac5f_434d_acf3_46b0d15e3dc6';\nSET mapreduce.job.split.metainfo.maxsize=-1;\nSET mapred.compress.map.output=true;\nSET mapred.map.output.compression.codec=com.hadoop.compression.lzo.LzoCodec;\nSET mapred.output.compress=true;\nSET mapred.output.compression.codec=com.hadoop.compression.lzo.LzoCodec;\nSET mapred.output.compression.type=BLOCK;\nSET mapreduce.job.max.split.locations=2000;\nSET hive.exec.compress.output=true;\nSET hive.auto.convert.join.noconditionaltask = true;\nSET hive.auto.convert.join.noconditionaltask.size = 300000000;\nINSERT OVERWRITE TABLE kylin_intermediate_test_kylin_cube_with_slr_desc_19700101000000_20140731160000_c143e0e4_ac5f_434d_acf3_46b0d15e3dc6\nSELECT\nTEST_KYLIN_FACT.CAL_DT\n,TEST_KYLIN_FACT.LEAF_CATEG_ID\n,TEST_KYLIN_FACT.LSTG_SITE_ID\n,TEST_CATEGORY_GROUPINGS.META_CATEG_NAME\n,TEST_CATEGORY_GROUPINGS.CATEG_LVL2_NAME\n,TEST_CATEGORY_GROUPINGS.CATEG_LVL3_NAME\n,TEST_KYLIN_FACT.LSTG_FORMAT_NAME\n,TEST_KYLIN_FACT.SLR_SEGMENT_CD\n,TEST_KYLIN_FACT.SELLER_ID\n,TEST_KYLIN_FACT.PRICE\nFROM TEST_KYLIN_FACT\nINNER JOIN TEST_CAL_DT\nON TEST_KYLIN_FACT.CAL_DT = TEST_CAL_DT.CAL_DT\nINNER JOIN TEST_CATEGORY_GROUPINGS\nON TEST_KYLIN_FACT.LEAF_CATEG_ID = TEST_CATEGORY_GROUPINGS.LEAF_CATEG_ID AND TEST_KYLIN_FACT.LSTG_SITE_ID = TEST_CATEGORY_GROUPINGS.SITE_ID\nINNER JOIN TEST_SITES\nON TEST_KYLIN_FACT.LSTG_SITE_ID = TEST_SITES.SITE_ID\nINNER JOIN TEST_SELLER_TYPE_DIM\nON TEST_KYLIN_FACT.SLR_SEGMENT_CD = TEST_SELLER_TYPE_DIM.SELLER_TYPE_CD\nWHERE (test_kylin_fact.cal_dt < '2014-07-31 16:00:00')\n;\n\"",
  18.          "interrupt_cmd":null,
  19.          "exec_start_time":0,
  20.          "exec_end_time":0,
  21.          "exec_wait_time":0,
  22.          "step_status":"PENDING",
  23.          "cmd_type":"SHELL_CMD_HADOOP",
  24.          "info":null,
  25.          "run_async":false
  26.       },
  27.       {  
  28.          "interruptCmd":null,
  29.          "name":"Extract Fact Table Distinct Columns",
  30.          "sequence_id":1,
  31.          "exec_cmd":" -conf C:/kylin/Kylin/server/src/main/resources/hadoop_job_conf_medium.xml -cubename test_kylin_cube_with_slr_empty -input /tmp/kylin-c143e0e4-ac5f-434d-acf3-46b0d15e3dc6/kylin_intermediate_test_kylin_cube_with_slr_desc_19700101000000_20140731160000_c143e0e4_ac5f_434d_acf3_46b0d15e3dc6 -output /tmp/kylin-c143e0e4-ac5f-434d-acf3-46b0d15e3dc6/test_kylin_cube_with_slr_empty/fact_distinct_columns -jobname Kylin_Fact_Distinct_Columns_test_kylin_cube_with_slr_empty_Step_1",
  32.          "interrupt_cmd":null,
  33.          "exec_start_time":0,
  34.          "exec_end_time":0,
  35.          "exec_wait_time":0,
  36.          "step_status":"PENDING",
  37.          "cmd_type":"JAVA_CMD_HADOOP_FACTDISTINCT",
  38.          "info":null,
  39.          "run_async":true
  40.       },
  41.       {  
  42.          "interruptCmd":null,
  43.          "name":"Load HFile to HBase Table",
  44.          "sequence_id":12,
  45.          "exec_cmd":" -input /tmp/kylin-c143e0e4-ac5f-434d-acf3-46b0d15e3dc6/test_kylin_cube_with_slr_empty/hfile/ -htablename KYLIN-CUBE-TEST_KYLIN_CUBE_WITH_SLR_EMPTY-19700101000000_20140731160000_11BB4326-5975-4358-804C-70D53642E03A -cubename test_kylin_cube_with_slr_empty",
  46.          "interrupt_cmd":null,
  47.          "exec_start_time":0,
  48.          "exec_end_time":0,
  49.          "exec_wait_time":0,
  50.          "step_status":"PENDING",
  51.          "cmd_type":"JAVA_CMD_HADOOP_NO_MR_BULKLOAD",
  52.          "info":null,
  53.          "run_async":false
  54.       }
  55.    ],
  56.    "job_status":"PENDING",
  57.    "progress":0.0
  58. }

## Pause Job
PUT /kylin/api/jobs/{jobId}/pause

Path variable

  • jobId - required string Job id.

Discard Job

PUT /kylin/api/jobs/{jobId}/cancel

Path variable

  • jobId - required string Job id.

Get Job Status

GET /kylin/api/jobs/{jobId}

Path variable

  • jobId - required string Job id.

Response Sample

(Same as “Resume Job”)

Get job step output

GET /kylin/api/jobs/{jobId}/steps/{stepId}/output

Path Variable

  • jobId - required string Job id.
  • stepId - required string Step id; the step id is composed by jobId with step sequence id; for example, the jobId is “fb479e54-837f-49a2-b457-651fc50be110”, its 3rd step id is “fb479e54-837f-49a2-b457-651fc50be110-3”,

Response Sample

  1. {  
  2.    "cmd_output":"log string"
  3. }

Get job list

GET /kylin/api/jobs

Request Variables

  • cubeName - optional string Cube name.
  • projectName - required string Project name.
  • status - optional int Job status, e.g. (NEW: 0, PENDING: 1, RUNNING: 2, STOPPED: 32, FINISHED: 4, ERROR: 8, DISCARDED: 16)
  • offset - required int Offset used by pagination.
  • limit - required int Jobs per page.
  • timeFilter - required int, e.g. (LAST ONE DAY: 0, LAST ONE WEEK: 1, LAST ONE MONTH: 2, LAST ONE YEAR: 3, ALL: 4)

For example, to get the job list in project ‘learn_kylin’ for cube ‘kylin_sales_cube’ in lastone week:

  1. GET: /kylin/api/jobs?cubeName=kylin_sales_cube&limit=15&offset=0&projectName=learn_kylin&timeFilter=1

Response Sample

  1. [
  2.   { 
  3.     "uuid": "9eb7bccf-4448-4578-9c29-552658b5a2ca", 
  4.     "last_modified": 1490957579843, 
  5.     "version": "2.0.0", 
  6.     "name": "Sample_Cube - 19700101000000_20150101000000 - BUILD - GMT+08:00 2017-03-31 18:36:08", 
  7.     "type": "BUILD", 
  8.     "duration": 936, 
  9.     "related_cube": "Sample_Cube", 
  10.     "related_segment": "53a5d7f7-7e06-4ea1-b3ee-b7f30343c723", 
  11.     "exec_start_time": 1490956581743, 
  12.     "exec_end_time": 1490957518131, 
  13.     "mr_waiting": 0, 
  14.     "steps": [
  15.       { 
  16.         "interruptCmd": null, 
  17.         "id": "9eb7bccf-4448-4578-9c29-552658b5a2ca-00", 
  18.         "name": "Create Intermediate Flat Hive Table", 
  19.         "sequence_id": 0, 
  20.         "exec_cmd": null, 
  21.         "interrupt_cmd": null, 
  22.         "exec_start_time": 1490957508721, 
  23.         "exec_end_time": 1490957518102, 
  24.         "exec_wait_time": 0, 
  25.         "step_status": "DISCARDED", 
  26.         "cmd_type": "SHELL_CMD_HADOOP", 
  27.         "info": { "endTime": "1490957518102", "startTime": "1490957508721" }, 
  28.         "run_async": false 
  29.       }, 
  30.       { 
  31.         "interruptCmd": null, 
  32.         "id": "9eb7bccf-4448-4578-9c29-552658b5a2ca-01", 
  33.         "name": "Redistribute Flat Hive Table", 
  34.         "sequence_id": 1, 
  35.         "exec_cmd": null, 
  36.         "interrupt_cmd": null, 
  37.         "exec_start_time": 0, 
  38.         "exec_end_time": 0, 
  39.         "exec_wait_time": 0, 
  40.         "step_status": "DISCARDED", 
  41.         "cmd_type": "SHELL_CMD_HADOOP", 
  42.         "info": {}, 
  43.         "run_async": false 
  44.       }
  45.     ],
  46.     "submitter": "ADMIN", 
  47.     "job_status": "FINISHED", 
  48.     "progress": 100.0 
  49.   }
  50. ]

Get Hive Table

GET /kylin/api/tables/{project}/{tableName}

Path Parameters

  • project - required string project name
  • tableName - required string table name to find.

Response Sample

  1. {
  2.     uuid: "69cc92c0-fc42-4bb9-893f-bd1141c91dbe",
  3.     name: "SAMPLE_07",
  4.     columns: [{
  5.         id: "1",
  6.         name: "CODE",
  7.         datatype: "string"
  8.     }, {
  9.         id: "2",
  10.         name: "DESCRIPTION",
  11.         datatype: "string"
  12.     }, {
  13.         id: "3",
  14.         name: "TOTAL_EMP",
  15.         datatype: "int"
  16.     }, {
  17.         id: "4",
  18.         name: "SALARY",
  19.         datatype: "int"
  20.     }],
  21.     database: "DEFAULT",
  22.     last_modified: 1419330476755
  23. }

Get Hive Tables

GET /kylin/api/tables

Request Parameters

  • project- required string will list all tables in the project.
  • ext- optional boolean set true to get extend info of table.

Response Sample

  1. [
  2.  {
  3.     uuid: "53856c96-fe4d-459e-a9dc-c339b1bc3310",
  4.     name: "SAMPLE_08",
  5.     columns: [{
  6.         id: "1",
  7.         name: "CODE",
  8.         datatype: "string"
  9.     }, {
  10.         id: "2",
  11.         name: "DESCRIPTION",
  12.         datatype: "string"
  13.     }, {
  14.         id: "3",
  15.         name: "TOTAL_EMP",
  16.         datatype: "int"
  17.     }, {
  18.         id: "4",
  19.         name: "SALARY",
  20.         datatype: "int"
  21.     }],
  22.     database: "DEFAULT",
  23.     cardinality: {},
  24.     last_modified: 0,
  25.     exd: {
  26.         minFileSize: "46069",
  27.         totalNumberFiles: "1",
  28.         location: "hdfs://sandbox.hortonworks.com:8020/apps/hive/warehouse/sample_08",
  29.         lastAccessTime: "1398176495945",
  30.         lastUpdateTime: "1398176495981",
  31.         columns: "struct columns { string code, string description, i32 total_emp, i32 salary}",
  32.         partitionColumns: "",
  33.         EXD_STATUS: "true",
  34.         maxFileSize: "46069",
  35.         inputformat: "org.apache.hadoop.mapred.TextInputFormat",
  36.         partitioned: "false",
  37.         tableName: "sample_08",
  38.         owner: "hue",
  39.         totalFileSize: "46069",
  40.         outputformat: "org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat"
  41.     }
  42.   }
  43. ]

Load Hive Tables

POST /kylin/api/tables/{tables}/{project}

Request Parameters

  • tables - required string table names you want to load from hive, separated with comma.
  • project - required String the project which the tables will be loaded into.

Response Sample

  1. {
  2.     "result.loaded": ["DEFAULT.SAMPLE_07"],
  3.     "result.unloaded": ["sapmle_08"]
  4. }

Wipe cache

PUT /kylin/api/cache/{type}/{name}/{action}

Path variable

  • type - required string ‘METADATA’ or ‘CUBE’
  • name - required string Cache key, e.g the cube name.
  • action - required string ‘create’, ‘update’ or ‘drop’

Initiate cube start position

Set the stream cube’s start position to the current latest offsets; This can avoid building from the earlist position of Kafka topic (if you have set a long retension time);

PUT /kylin/api/cubes/{cubeName}/init_start_offsets

Path variable

  • cubeName - required string Cube name

Response Sample

  1. {
  2.     "result": "success", 
  3.     "offsets": "{0=246059529, 1=253547684, 2=253023895, 3=172996803, 4=165503476, 5=173513896, 6=19200473, 7=26691891, 8=26699895, 9=26694021, 10=19204164, 11=26694597}"
  4. }

Build stream cube

PUT /kylin/api/cubes/{cubeName}/build2

This API is specific for stream cube’s building;

Path variable

  • cubeName - required string Cube name

Request Body

  • sourceOffsetStart - required long The start offset, 0 represents from previous position;
  • sourceOffsetEnd - required long The end offset, 9223372036854775807 represents to the end position of current stream data
  • buildType - required Build type, “BUILD”, “MERGE” or “REFRESH”

Request Sample

  1. {  
  2.    "sourceOffsetStart": 0, 
  3.    "sourceOffsetEnd": 9223372036854775807, 
  4.    "buildType": "BUILD"
  5. }

Response Sample

  1. {
  2.     "uuid": "3afd6e75-f921-41e1-8c68-cb60bc72a601", 
  3.     "last_modified": 1480402541240, 
  4.     "version": "1.6.0", 
  5.     "name": "embedded_cube_clone - 1409830324_1409849348 - BUILD - PST 2016-11-28 22:55:41", 
  6.     "type": "BUILD", 
  7.     "duration": 0, 
  8.     "related_cube": "embedded_cube_clone", 
  9.     "related_segment": "42ebcdea-cbe9-4905-84db-31cb25f11515", 
  10.     "exec_start_time": 0, 
  11.     "exec_end_time": 0, 
  12.     "mr_waiting": 0, 
  13.  ...
  14. }

Check segment holes

GET /kylin/api/cubes/{cubeName}/holes

Path variable

  • cubeName - required string Cube name

Fill segment holes

PUT /kylin/api/cubes/{cubeName}/holes

Path variable

  • cubeName - required string Cube name

Use RESTful API in Javascript

Keypoints of call Kylin RESTful API in web page are:

  1. Add basic access authorization info in http headers.

  2. Use proper request type and data synax.

Kylin security is based on basic access authorization, if you want to use API in your javascript, you need to add authorization info in http headers; for example:

  1. $.ajaxSetup({
  2.       headers: { 'Authorization': "Basic eWFu**********X***ZA==", 'Content-Type': 'application/json;charset=utf-8' } // use your own authorization code here
  3.     });
  4.     var request = $.ajax({
  5.        url: "http://hostname/kylin/api/query",
  6.        type: "POST",
  7.        data: '{"sql":"select count(*) from SUMMARY;","offset":0,"limit":50000,"acceptPartial":true,"project":"test"}',
  8.        dataType: "json"
  9.     });
  10.     request.done(function( msg ) {
  11.        alert(msg);
  12.     }); 
  13.     request.fail(function( jqXHR, textStatus ) {
  14.        alert( "Request failed: " + textStatus );
  15.   });

To generate your authorization code, download and import “jquery.base64.js” from https://github.com/yckart/jquery.base64.js).

  1. var authorizationCode = $.base64('encode', 'NT_USERNAME' + ":" + 'NT_PASSWORD');
  3. $.ajaxSetup({
  4.    headers: { 
  5.     'Authorization': "Basic " + authorizationCode, 
  6.     'Content-Type': 'application/json;charset=utf-8' 
  7.    }
  8. });