API docs by Redocly

BKN Metrics (0.1.0)

Download OpenAPI specification:

Modeling CRUD for BKN native metrics: create, list, validate, update, and delete.

Supported matrix (current implementation)

Capability Status Notes
metric_type=atomic with scope_type=object_type Writable and queryable Supported by strict writes and ontology-query execution
calculation_formula.condition, including and/or combinations Writable Isomorphic with ontology-query Condition; see query documentation for merge semantics
time_dimension, having, and analysis_dimensions Partially available Fields can be persisted; verify end-to-end query behavior in ontology-query
metric_type=derived and composite Future The schema reserves these values; strict writes and dry-run reject them and accept atomic only
scope_type=subgraph Future The schema reserves it; writes and dry-run accept object_type only

Querying and dry-run (not in this file)

Metric data queries and dry-run are provided by ontology-query, not BKN Backend CRUD.

  • Query persisted metrics with POST /api/ontology-query/v1/knowledge-networks/{kn_id}/metrics/{metric_id}/data
  • Run a dry-run without persistence with POST /api/ontology-query/v1/knowledge-networks/{kn_id}/metrics/dry-run
  • Request body: MetricQueryRequestBody with condition, analysis_dimensions, time, having, and limit

See the contract in ontology-query.yaml. Refer to the metric data and dry-run paths and the MetricQueryRequestBody and MetricDryRun schemas. Consult ontology-query for condition merge semantics and the relationship between analysis_dimensions and group_by.

Product note: object instance execution targets logical properties. Object-type aggregate metrics must use metric data or dry-run rather than the instance execution entry point.

List metrics

path Parameters
kn_id
required
string

Business knowledge network ID

query Parameters
name_pattern
string

Fuzzy match by name. Defaults to empty.

sort
string
Enum: "update_time" "name"

Sort type. Defaults to update_time.

direction
string
Enum: "asc" "desc"

Sort direction. Supported values are asc and desc. Defaults to desc.

offset
integer <int64>

Offset of the first returned item. Must be greater than or equal to 0. Defaults to 0.

limit
integer <int64>

Maximum number of items returned per page. Pagination accepts 1 through 1000, and -1 disables pagination. Defaults to 10.

tag
string

Exact match by tag. Defaults to empty.

branch
string

Branch. Uses main when omitted.

scope_type
string
Enum: "object_type" "subgraph"

Filter by metric scope type. The current implementation writes object_type only. subgraph is future work; see the supported matrix in info.description.

scope_ref
string

Filter by the concept ID referenced by the metric scope, such as an object type ID. Multiple comma-separated IDs are supported; a match for any ID is returned. Use this to list metrics for multiple object types. When scope_ref is provided without scope_type, scope_type defaults to object_type.

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "total_count": 0
}

Create metrics in batch or retrieve metrics by concept

This follows POST object-types and uses x-http-method-override to select semantics.

  • POST creates metrics in batch with a ReqMetrics entries array. Strict mode accepts metric_type=atomic and scope_type=object_type only.
  • GET retrieves by concept or condition with cursor pagination, using the same body as object type retrieval. Use ontology-query metric data or dry-run to query or calculate metrics after creation.
path Parameters
kn_id
required
string

Business knowledge network ID

query Parameters
branch
string

Branch. Uses main when omitted.

strict_mode
boolean
Default: true

Whether to strictly validate dependencies during batch creation, such as scope and concept groups. Defaults to true.

import_mode
string
Default: "normal"
Enum: "normal" "overwrite" "ignore"

Import mode. normal reports an error for duplicate concept names; overwrite replaces them; ignore skips them. Defaults to normal.

header Parameters
x-http-method-override
required
string
Enum: "POST" "GET"

Request override header

Request Body schema: application/json
required
required
Array of objects (CreateMetricRequest)

Metrics to create

Responses

Request samples

Content type
application/json
Example
{
  • "entries": [
    ],
  • "x-http-method-override": "x-http-method-override:POST"
}

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "total_count": 0,
  • "next_cursor": "string",
  • "groups": [
    ],
  • "type": "string"
}

Validate metrics

Validates dependency existence without persisting data. Its semantics match POST object-types/validation and it is intended for pre-import and pre-batch checks. Response: HTTP 200 with valid=true means validation passed. valid=false includes detail.

path Parameters
kn_id
required
string

Business knowledge network ID

query Parameters
branch
string

Branch. Uses main when omitted.

strict_mode
boolean
Default: true

Whether to strictly validate dependencies. Defaults to true.

import_mode
string
Default: "normal"
Enum: "normal" "ignore" "overwrite"

Matches batch creation semantics and validates conflicts with persisted metric IDs or names using normal, ignore, or overwrite.

Request Body schema: application/json
required
Array of objects (CreateMetricRequest)

Metrics to validate. Uses the same structure as the creation API.

Responses

Request samples

Content type
application/json
{
  • "entries": [
    ]
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "detail": "string"
}

Batch get metric details

path Parameters
metric_ids
required
Array of strings

Metric ID list

kn_id
required
string

Business knowledge network ID

query Parameters
branch
string

Branch. Uses main when omitted.

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ]
}

Update a metric

Updates a metric definition. The metrics/{metric_ids} route is shared with batch get and delete. Requires application/json content type.

path Parameters
kn_id
required
string

Business knowledge network ID

metric_ids
required
string

Metric ID

query Parameters
branch
string

Branch. Uses main when omitted.

strict_mode
boolean
Default: true

Whether to strictly validate dependencies. Defaults to true.

Request Body schema: application/json
required
comment
string
tags
Array of strings
icon
string
color
string
unit_type
string (MetricUnitType)
Enum: "numUnit" "storeUnit" "percent" "transmissionRate" "timeUnit" "currencyUnit" "percentageUnit" "countUnit" "weightUnit" "ordinalRankUnit"

Metric unit type. The value must be one of the following enum members and matches the bkn-backend interfaces.ValidMetricUnitTypes validation.

unit
string (MetricUnit)
Enum: "none" "K" "Mil" "Bil" "Tri" "bit" "Byte" "KB" "MB" "GB" "TB" "PB" "bps" "Kbps" "Mbps" "μs" "ms" "s" "m" "h" "day" "week" "month" "year" "quarter" "Fen" "Jiao" "CNY" "10K_CNY" "1M_CNY" "100M_CNY" "US_Cent" "USD" "EUR_Cent" "%" "‰" "household" "transaction" "piece" "item" "times" "man_day" "family" "hand" "sheet" "packet" "ton" "kg" "rank"

Metric unit. The value must be one of the following enum members and matches the bkn-backend interfaces.ValidMetricUnits validation.

metric_type
string
Enum: "atomic" "derived" "composite"

Metric type. The enum reserves derived and composite for future work. Strict updates currently accept atomic only.

object (MetricTimeDimension)

Time dimension, DESIGN appendix B.2

object (MetricCalculationFormula)

Metric calculation formula with a condition isomorphic with ontology-query Condition, DESIGN appendix B.1

Array of objects (MetricAnalysisDimension)

Responses

Request samples

Content type
application/json
{
  • "comment": "string",
  • "tags": [
    ],
  • "icon": "string",
  • "color": "string",
  • "unit_type": "numUnit",
  • "unit": "none",
  • "metric_type": "atomic",
  • "time_dimension": {
    },
  • "calculation_formula": {
    },
  • "analysis_dimensions": [
    ]
}

Delete metrics in batch

path Parameters
kn_id
required
string

Business knowledge network ID

metric_ids
required
Array of strings

Metric ID list

query Parameters
branch
string

Branch. Uses main when omitted.

Responses