FuseQL API for logs :: Kloudfuse Docs

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:

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

Mutations

Prerequisites

getLogMetricsResultWithKfuseQl

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

Syntax

{ (1)
  getLogMetricsResultWithKfuseQl(
    query: String! (2)
    startTs: Time! (3)
    endTs: Time! (4)
    timeoutSecs: Int (5)
    options: String (6)
  ): FuseQLQueryResult (7)
}
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 header)

- 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
  }
}

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)
}
1 subscription:
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
      }
    }

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=="
    }
  }
}

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
      }
    }

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)
}
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
  }
}

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\
      }\
    ]
  }
}

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)
}
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
  )
}

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
}

Response

{
  "data": {
    "createDimensionTable": true
  }
}

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)
}

Examples

Delete lookup table

mutation {
  deleteDimensionTable(tableName: "cluster_costs")
}

Response

{
  "data": {
    "deleteDimensionTable": true
  }
}

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)
}

Examples

Move a lookup table to a different folder

mutation {
  editLookupTable(
    tableName: "UserLocations"
    editInfo: {
      newFolderUid: "xyz789"
    }
  )
}

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
    }
  )
}

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
    }
  )
}

Move table and update data simultaneously

mutation {
  editLookupTable(
    tableName: "ProductInformation"
    editInfo: {
      newFolderUid: "folder456"
      file: <CSV_FILE_UPLOAD>
      overwrite: false
    }
  )
}