FuseQL API for logs

To interact programmatically with FuseQL logs, you must issue the required query requests.

The FuseQL query is embedded within the GraphQL request arguments. FuseQL works with tables, so the result of the FuseQL query is often a table that follows a schema defined by the column headers.

Embed the supported FuseQL query within the graphQL request arguments. See instructions on how to use GraphQL.

For authorization, see Service Accounts.

Kloudfuse offers these FuseQL queries:

getLogMetricsResultWithKfuseQl

Get a time series of metrics derived from logs for the specified time range using native Kloudfuse query engine.

getLogsWithFuseQlStream

Get logs for the specified time range, using the native Kloudfuse query engine.

For additional log APIs, see API for Logs.

Lookup Table Operations

Kloudfuse provides GraphQL queries and mutations to manage lookup tables programmatically. These tables can be used with the lookup operator to enrich log data.

Queries

[getLookUpTables]

Retrieve a list of all lookup tables with their configuration details.

Mutations

createLookupTable

Create a new lookup table by uploading a CSV file with specified primary keys and dimensions.

deleteLookupTable

Delete an existing lookup table.

editLookupTable

Edit an existing lookup table by updating its folder location or data.

Prerequisites

  • Configure a GraphQL client. See GraphQL documentation.

  • Authenticate using the basic HTTP authentication protocol.

getLogMetricsResultWithKfuseQl

Get a time series of metrics derived from logs for the specified time range using native Kloudfuse query engine.

Syntax
{ (1)
  getLogMetricsResultWithKfuseQl(
    query: String! (2)
    startTs: Time! (3)
    endTs: Time! (4)
    timeoutSecs: Int (5)
    options: String (6)
  ): FuseQLQueryResult (7)
}
none
1 This is a query; calls return a single response.
2 query: Query of logs, including all operators.
3 startTS: Start timestamp of a query; should be less than endTs because it must be earlier.
4 endTS: End timestamp of a query; should be more than endTs because it must be later.
5 timeoutSecs: Optional query timeout, in seconds; default is 60 seconds.
6 options: Query options; string of comma-separated k=v key-value pairs. Not implemented — DO NOT USE.
7 FuseQLQueryResult Returns the following:

  • AggrValues (list of aggregation column headers)

  • ColumnHeaders (list of column names in the FuseQL result)

  • GroupKeys (list of groups by column headers)

  • TimeKey (time bucket column heade)r

  • TableResult (rows returned from the FuseQL query)

  • UrlValues (list of URL column headers)
Examples
Initial query
{
  getLogMetricsResultWithKfuseQl(
    query: "* | timeslice 5s | count by (_timeslice)"
    startTs: "2025-04-09T12:04:50-07:00"
    endTs: "2025-04-09T12:09:50-07:00"
  ) {
    AggrValues
    ColumnHeaders
    GroupKeys
    TimeKey
    TableResult
    UrlValues
  }
}
none

getLogsWithFuseQlStream

Get logs for the specified time range, using the native Kloudfuse query engine.

This API is relatively limited. By default, the system sorts the results by timestamp, in descending order, and retrieves up to 200 results. You must use a looping mechanism to retrieve all results, until the end of read.

Syntax
subscription { (1)
  getLogsWithFuseQlStream(
    query: String! (2)
    startTs: Time! (3)
    endTs: Time! (4)
    cursor: String (5)
    timeoutSecs: Int (6)
    options: String (7)
  ): FuseQLQueryResult (8)
}
none
1 subsription: This is a subscription; calls return multiple responses.
2 query: Query of logs, including all operators, except Window and Aggregation.
3 startTS: Start timestamp of a query; should be less than endTs because it must be earlier.
4 endTS: End timestamp of a query; should be more than endTs because it must be later.
5 cursor: Pagination cursor. It must be null for the first GraphQL query; subsequent queries must include values from the previous response. If the returned cursor is empty, there are no more results left to fetch.
6 timeoutSecs: Optional query timeout, in seconds; default is 60 seconds.
7 options: Query options; string of comma-separated k=v key-value pairs. Not implemented — DO NOT USE.
8 FuseQLQueryResult: Returns the following:

  • TableResult (rows returned from the FuseQL query)

  • ColumnHeaders (list of column names in the FuseQL result)

  • Cursor (opaque cursor returned to help in pagination; empty string when no more data to fetch).
Examples
Initial query
    subscription {
      getLogsWithFuseQlStream(
        cursor: null,
        query: "source=\"kfuseprofiler\"",
        startTs:  "2025-04-04T09:00:00-07:00",
        endTs: "2025-04-04T10:00:00-07:00",
      ) {
        TableResult
        ColumnHeaders
        Cursor
      }
    }
none
Response
{
  "data": {
    "getLogsWithFuseQlStream": {
      "ColumnHeaders": [
        "timestamp",
        "source",
        "logLine",
        "fpString",
        "fpHash",
        "level",
        "labels",
        "facets"
      ],
      "TableResult": [
        [
          1743783475585,
          "kfuseprofiler",
          "[DEBUG] content type: multipart/form-data; boundary=dc38d23cb110dc72e94dbc64fef4f7591041ebc99b5bd5c83c4f55d10d5b",
           .
           .
           .
        ]
      ],
      "Cursor": "eyJzb3J0QnlWYWwiOiIxNzQzNzgyNzU1NTM5Iiwib2Zmc2V0IjoyfQ=="
    }
  }
}
none
Next query
    subscription {
      getLogsWithFuseQlStream(
        cursor: "eyJzb3J0QnlWYWwiOiIxNzQzNzgyNzU1NTM5Iiwib2Zmc2V0IjoyfQ==",
        query: "source=\"kfuseprofiler\"",
        startTs:  "2025-04-04T09:00:00-07:00",
        endTs: "2025-04-04T10:00:00-07:00",
      ) {
        TableResult
        ColumnHeaders
        Cursor
      }
    }
none

getLookupTables

Retrieve a list of all lookup tables with their configuration details, including table names, dimensions, primary keys, and folder locations.

Syntax
query { (1)
  getLookUpTables: [LookupTableConfig] (2)
}

type LookupTableConfig { (3)
  TableName: String (4)
  Dimensions: [NameAndDataType] (5)
  PrimaryKeyColumns: [String!]! (6)
  FolderUid: String (7)
}

type NameAndDataType { (8)
  Name: String! (9)
  DataType: String! (10)
}
code
1 query: This is a query operation that retrieves data without modifying it.
2 getLookUpTables: Returns an array of LookupTableConfig objects, one for each lookup table in your workspace.
3 LookupTableConfig: The configuration object for a lookup table.
4 TableName: The name of the lookup table.
5 Dimensions: Array of dimension definitions, each containing the column name and data type.
6 PrimaryKeyColumns: Required. Array of column names that serve as primary keys for the table.
7 FolderUid: The unique identifier of the folder containing the table. May be null if the table is in the default location.
8 NameAndDataType: Object defining a column’s name and data type.
9 Name: The column name.
10 DataType: The data type of the column (e.g., string, int, long, float, double, boolean).
Examples
Retrieve all lookup tables
query {
  getLookUpTables {
    TableName
    Dimensions {
      Name
      DataType
    }
    PrimaryKeyColumns
    FolderUid
  }
}
code
Response example
{
  "data": {
    "getLookUpTables": [
      {
        "TableName": "UserLocations",
        "Dimensions": [
          {
            "Name": "userID",
            "DataType": "string"
          },
          {
            "Name": "country",
            "DataType": "string"
          },
          {
            "Name": "city",
            "DataType": "string"
          },
          {
            "Name": "latitude",
            "DataType": "float"
          },
          {
            "Name": "longitude",
            "DataType": "float"
          }
        ],
        "PrimaryKeyColumns": ["userID"],
        "FolderUid": "abc123"
      },
      {
        "TableName": "ErrorCodes",
        "Dimensions": [
          {
            "Name": "errorCode",
            "DataType": "string"
          },
          {
            "Name": "version",
            "DataType": "string"
          },
          {
            "Name": "errorDescription",
            "DataType": "string"
          },
          {
            "Name": "severity",
            "DataType": "string"
          }
        ],
        "PrimaryKeyColumns": ["errorCode", "version"],
        "FolderUid": null
      }
    ]
  }
}
code

createLookupTable

Create a new lookup table (lookup table) by uploading a CSV file. The table can be used with the lookup operator to enrich log data with additional context.

Syntax
mutation { (1)
  createDimensionTable(
    tableName: String! (2)
    dimensions: [NameAndDataTypeInput!]! (3)
    file: Upload! (4)
    primaryKeyColumns: [String!]! (5)
    folderUid: String (6)
  ): Boolean (7)
}
none
1 This is a mutation; creates or modifies data.
2 tableName: The unique name for the lookup table.
3 dimensions: Array of column definitions with Name and DataType fields. Supported DataTypes: STRING, INTEGER, DOUBLE.
4 file: The CSV file to upload containing the lookup data.
5 primaryKeyColumns: Array of column names that form the primary key for lookups.
6 folderUid: Optional folder identifier for organization.
7 Returns true if the table was created successfully.
Examples
Create lookup table
mutation createDimensionTable(
  $tableName: String!,
  $dimensions: [NameAndDataTypeInput!]!,
  $file: Upload!,
  $primaryKeyColumns: [String!]!,
  $folderUid: String
) {
  createDimensionTable(
    tableName: $tableName,
    dimensions: $dimensions,
    file: $file,
    primaryKeyColumns: $primaryKeyColumns,
    folderUid: $folderUid
  )
}
none
Variables
{
  "tableName": "cluster_costs",
  "dimensions": [
    {"Name": "ClusterName", "DataType": "STRING"},
    {"Name": "StreamType", "DataType": "STRING"},
    {"Name": "StoredVolume(TB)", "DataType": "STRING"},
    {"Name": "GiB-HourPrice($)", "DataType": "STRING"},
    {"Name": "DailyCost($)", "DataType": "STRING"},
    {"Name": "MonthlyCost($)", "DataType": "STRING"}
  ],
  "primaryKeyColumns": ["ClusterName"],
  "file": null
}
none
Response
{
  "data": {
    "createDimensionTable": true
  }
}
none
Python implementation
import json
import requests

# Simple CSV upload to create lookup table
with open('data.csv', 'rb') as f:
    response = requests.post(
        'https://your-instance.kloudfuse.com/query',
        files={
            'operations': (None, json.dumps({
                'query': '''mutation($tableName: String!, $dimensions: [NameAndDataTypeInput!]!,
                                   $file: Upload!, $primaryKeyColumns: [String!]!) {
                    createDimensionTable(tableName: $tableName, dimensions: $dimensions,
                                       file: $file, primaryKeyColumns: $primaryKeyColumns)
                }''',
                'variables': {
                    'tableName': 'my_table',
                    'dimensions': [
                        {'Name': 'ClusterName', 'DataType': 'STRING'},
                        {'Name': 'Cost', 'DataType': 'STRING'}
                    ],
                    'primaryKeyColumns': ['ClusterName']
                }
            })),
            'map': (None, '{"0": ["variables.file"]}'),
            '0': ('data.csv', f, 'text/csv')
        },
        auth=('username', 'password')
    )

print(response.json())
python

deleteLookupTable

Delete an existing lookup table. This operation is permanent and cannot be undone.

Deleting a lookup table will cause any queries using the lookup operator with this table to fail. Ensure the table is not in use before deletion.
Syntax
mutation { (1)
  deleteDimensionTable(
    tableName: String! (2)
  ): Boolean (3)
}
javascript
1 mutation: This is a mutation operation that modifies data on the server.
2 tableName: The name of the lookup table to delete.
3 Boolean!: Returns true if the table was deleted successfully, false otherwise.
Examples
Delete lookup table
mutation {
  deleteDimensionTable(tableName: "cluster_costs")
}
none
Response
{
  "data": {
    "deleteDimensionTable": true
  }
  ): Boolean! (3)
}
javascript

editLookupTable

Edit an existing lookup table by updating its folder location or adding data with a new CSV file. When uploading a new CSV file, the schema (columns and data types) must match the existing table.

When updating table data with a new CSV file:

  • If overwrite is false (default): Rows with conflicting primary keys will be replaced with the new values, and rows with new primary keys will be appended to the table.

  • If overwrite is true: The entire table data will be replaced with the contents of the new CSV file.
Syntax
mutation { (1)
  editLookupTable(
    tableName: String! (2)
    editInfo: EditLookupTableInput! (3)
  ): Boolean! (4)
}

input EditLookupTableInput {
  newFolderUid: String (5)
  file: Upload (6)
  overwrite: Boolean (7)
}
javascript
1 mutation: This is a mutation operation that modifies data on the server.
2 tableName: Required. The name of the lookup table to edit.
3 editInfo: Required. An object containing the fields to update. At least one field must be provided.
4 Boolean!: Returns true if the table was updated successfully, false otherwise.
5 newFolderUid: Optional. The unique identifier of the folder to move the table to. Use this to reorganize tables across folders.
6 file: Optional. A new CSV file to update the table data. The file must have the same schema (columns and data types) as the original table. Maximum file size is 50 MB.
7 overwrite: Optional. If true, the entire table data will be replaced with the contents of the new CSV file. If false, the new CSV data will be merged with the existing data.

  • false (default): Merge mode - rows with matching primary keys are updated, new rows are appended.

  • true: Replace mode - the entire table data is replaced with the new CSV file contents.
Examples
Move a lookup table to a different folder
mutation {
  editLookupTable(
    tableName: "UserLocations"
    editInfo: {
      newFolderUid: "xyz789"
    }
  )
}
javascript
Update lookup table data with a new CSV file (merge mode)
mutation {
  editLookupTable(
    tableName: "ErrorCodes"
    editInfo: {
      file: <CSV_FILE_UPLOAD>
      overwrite: false  # Merge: update matching rows, append new rows
    }
  )
}
javascript
Replace entire table data with a new CSV file
mutation {
  editLookupTable(
    tableName: "ErrorCodes"
    editInfo: {
      file: <CSV_FILE_UPLOAD>
      overwrite: true  # Replace: discard all existing data
    }
  )
}
javascript
Move table and update data simultaneously
mutation {
  editLookupTable(
    tableName: "ProductInformation"
    editInfo: {
      newFolderUid: "folder456"
      file: <CSV_FILE_UPLOAD>
      overwrite: false
    }
  )
}
javascript