pmapisearch.md

GET /pmapi/search

enum schema_field {
	type, name, indom, oneline, helptext
};

enum types {
	metric: 0,
	instance: 1,
	indom: 2,
};

Parameters	Type	Explanation
query (required, <20 chars)	string	string to be passed to Redisearch
highlight (default=false)	boolean	toggles highlighting for help fields
offset (default=0)	number	number of records to skip
limit (default=5)	number	number of records per page
field (default=null)	schema_field[] - type	queried fields, null = all
return (default=null)	schema_field[]	fields to actually return, null = all
type (default=null)	types[]	entity types to filter

RediSearch query composition:

formatted_query = query with dots replaced by spaces
[] = optional part
{var} = query param value

FT.SEARCH pcp:fulltext "{formatted_query} [@type={ {?type separated by pipe} }]"
	[INFIELDS {?field item count} {?field separated by space}]
	[RETURN {?return item count} {?return separated by space}]
	[HIGHLIGHT 2 oneline helptext]
	LIMIT {?offset} {?limit}

Example queries

Schema creation:

FT.CREATE pcp:fulltext SCHEMA type TAG name TEXT WEIGHT 10.0 SORTABLE indom TEXT NOSTEM WEIGHT 0 oneline TEXT WEIGHT 4.0 helptext TEXT WEIGHT 2.0

Sample metric record:

FT.ADD pcp:fulltext 489dbe44c0fd4746fed850433b9eab1af5bee1b5 1.0 FIELDS type "0" name "kernel.uname.distro" indom "PM_INDOM_NULL" oneline "Linux distribution name" helptext "The Linux distribution name, as determined by a number of heuristics. \nFor example:\n + on Fedora, the contents of /etc/fedora-release\n + on RedHat, the contents of /etc/redhat-release"

Example searches

FT.SEARCH pcp:fulltext "kernel"
FT.SEARCH pcp:fulltext "example"

Highlight param example:

FT.SEARCH pcp:fulltext {query} HIGHLIGHT FIELDS 2 oneline helptext

Offset and limit example:

FT.SEARCH pcp:fulltext {query} LIMIT {offset} {limit}

Limiting search and return values to certain fields only

FT.SEARCH pcp:fulltext {query} INFIELDS {?field field count} {?field separated by space} RETURN {?return field count} {?return separated by space}

Sample instance domain record with related metric:

FT.ADD pcp:fulltext d95f683f17c9f1ee05edf25e59fc8deba376ba27 1.0 FIELDS name "60.3" type "2" indom "60.3" oneline "set of network interfaces" helptext "set of network interfaces"
FT.ADD pcp:fulltext 77c80fa867cc066fca97a6a1e33d9579a3d48f65 1.0 FIELDS name "network.interface.speed" type "0" indom "60.3" oneline "interface speed in megabytes per second" helptext "The linespeed on the network interface, as reported by the kernel, scaled from Megabits/second to Megabytes/second. See also network.interface.baudrate for the bytes/second value."

Limiting search to entity type:

FT.SEARCH pcp:fulltext "{query} @type:{ {...?type values separated by pipe} }"

Responses

interface PmApiSearchItemResponse {
	id: string, // docId from redisearch
	/* All the ones below may be omited when they are filtered out by ?return param, or whey they lack any value (helptexts for example) */
	name?: string, // name field
	type?: number, // type field (we always have only single type value on any record)
	indom?: string, // indom field
	oneline?: string, // oneline field
	helptext?: string, // helptext field
};

interface PmApiSearchResponse {
	items: PmApiSearchItemResponse[],
	limit: number,
	offset: number,
	total: number, // Redisearch returns total number of matching records even if results themselves are limited
};