Class Reference
IRIS for UNIX 2024.1.2
|
Class Reference
IRIS for UNIX 2024.1.2
|
|
|
Private
Storage
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Please note this version of the REST API is deprecated. See
This class offers endpoints for accessing iKnow functionalities over REST.
The API is fully documented using the OpenAPI Specification (also known as Swagger). The description in YAML is available from the "/swagger" endpoint and can be loaded directly into swagger-ui for convenient GUI capabilities on top of this API.
swagger: '2.0'
info:
version: "1.0.0"
title: iKnow REST APIs
description: |
This is the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification)
of the iKnow REST APIs, giving you RESTful access to iKnow domain contents in your system
Use [swagger-ui](https://github.com/swagger-api/swagger-ui/blob/master/README.md)
or a similar tool to conveniently browse and test these APIs.
For more information on iKnow, visit [intersystems.com](http://www.intersystems.com)
contact:
name: InterSystems
url: http://wrc.intersystems.com
email: support@intersystems.com
license:
name: Copyright InterSystems Corporation, all rights reserved.
url: https://www.intersystems.com/noticesterms-conditions/
consumes:
- application/json
produces:
- application/json
parameters:
domainParam:
name: domain
type: integer
in: path
description: the ID of the domain to query
required: true
sourceParam:
name: source
type: integer
in: path
description: the source ID to query for
required: true
tableParam:
name: table
type: string
in: path
description: the table containing iFind index
required: true
definitions:
PageNumber:
type: integer
description: |
which "page" of the results to retrieve
default: 1
PageSize:
type: integer
description: |
how many results to retrieve per "page"
default: {{{PAGESIZE}}}
FilterMode:
description: filter mode to use for optionally recalculating certain metrics. Defaults to recalculating all and re-sorting the results (15).
type: integer
default: 15
example: 15
enum: [1, 3, 5, 7, 11, 13, 15]
IncludeCount:
description: whether or not to include a count of all results (ignoring page and pageSize)
type: boolean
default: 0
format: integer
CountOnly:
description: whether or not to retrieve just the count and no result list
type: boolean
default: 0
format: integer
Blacklists:
description: array of blacklist IDs or names to use for limiting query results, OR a valid SELECT clause retrieving entity values outright
type: array
default: []
items:
type: string
Filter:
# TODO: move into proper hierarchy once swagger-ui supports it
description: filter object restricting the sources to be considered in this query
type: object
example:
{ "operator": "OR",
"filters": [ { "ids": [ 123 ] },
{"field": "Year", "operator": ">", "value": 2016 } ] }
properties:
ids:
description: for use with source-ID-based filters
type: array
items:
type: integer
extIds:
description: for use with external-ID-based filters
type: array
items:
type: string
operator:
description: for use with group filters ("AND"|"OR") or metadata-based filters (any other value)
type: string
enum: ["AND", "OR", "=", "!=", "<", ">", ">=", "<=", "BETWEEN", "IS NULL", "IS NOT NULL"]
field:
description: for use with metadata-based filters
type: string
value:
description: for use with metadata-based filters
type: string
negate:
description: for use with group filters
type: boolean
default: false
filters:
description: for use with group filters
type: array
items:
$ref: '#/definitions/Filter'
className:
description: use for filters not covered by other shorthands
type: string
example: '%iKnow.Filters.ContainsEntityFilter'
arguments:
description: for use with 'className' property, any arguments to be passed to the filter's %New() method (except domain ID)
type: array
items:
type: string
HighlightingRule:
description: |
"style" property is mandatory, then pick one selector per rule
type: object
required: ["style"]
properties:
style:
type: string
description: |
style specification for this highlighting rule: either a two-character
sequence or a HTML tag to use for wrapping the to-be-highlighted element.
Use one selector per highlighting rule.
entities:
type: array
items:
type: string
description: <i>selector</i> - selects list of entities
role:
type: string
enum: ["concept", "relation", "pathRelevant", "nonRelevant" ]
description: <i>selector</i> - selects all entities with this role
attribute:
type: string
enum: ["negation", "positiveSentiment", "negativeSentiment" ]
description: <i>selector</i> - selects all entities affected by this attribute
attributeWords:
type: string
enum: ["negation", "positiveSentiment", "negativeSentiment" ]
description: <i>selector</i> - selects all marker terms indicating this attribute
anyMatch:
type: boolean
description: <i>selector</i> - selects any dictionary match
dictionaries:
type: array
description: <i>selector</i> - selects any dictionary match of the specified dictionary IDs
items:
type: integer
dictionaryItems:
type: array
description: <i>selector</i> - selects any dictionary match of the specified dictionary item IDs
items:
type: integer
matchType:
type: string
enum: ["full", "partial"]
description: |
refines the "anyMatch", "dictionaries" or "dictionaryItems" selectors to the designated match type
Highlighting:
description: array of highlighting rules
example:
[ { "style": "[]", "role": "concept" },
{ "style": "<b>", "entities": [ "airplane", "pilot" ] } ]
type: array
items:
$ref: '#/definitions/HighlightingRule'
DomainList:
type: object
required: ["domains"]
properties:
domains:
type: array
items:
title: Domain
type: object
required: ["id", "name" ]
properties:
id:
type: integer
name:
type: string
definitionClass:
type: string
sourceCount:
type: integer
version:
type: integer
DomainDetails:
type: object
required: ["id", "name"]
properties:
id:
type: integer
name:
type: string
parameters:
type: object
metadata:
type: array
items:
type: object
required: ["id", "name", "operators", "dataType", "storage"]
properties:
id:
type: integer
name:
type: string
operators:
type: array
items:
$ref: '#/definitions/MetadataOperator'
dataType:
type: string
enum: ["string", "number", "date"]
storage:
type: string
MetadataOperator:
type: string
enum: [ "=", "!=", "<", ">", ">=", "<=", "BETWEEN", "IS NULL", "IS NOT NULL" ]
ConfigurationList:
type: object
required: ["configurations"]
properties:
configurations:
type: array
items:
title: Configuration
type: object
required: ["id", "name", "languages"]
properties:
id:
type: integer
name:
type: string
languages:
type: array
items:
$ref: '#/definitions/LanguageCode'
userDictionary:
$ref: '#/definitions/UserDictionary'
maxConceptLength:
type: integer
UserDictionary:
type: object
required: ["entries"]
properties:
name:
type: string
entries:
type: array
items:
title: UserDictionaryEntry
type: object
required: ["string"]
properties:
string:
type: string
rewrite:
type: string
label:
type: string
LanguageCode:
description: 2-letter ISO language code
type: string
enum: [ "en", "fr", "de", "es", "pt", "nl", "ru", "uk", "se", "ja" ]
SourceList:
description: list of sources
type: object
required: ["sources"]
properties:
sources:
type: array
items:
title: Source
type: object
required:
- id
- extId
properties:
id:
type: integer
description: source ID
extId:
type: string
description: external ID
metadata:
type: object
description: map of metadata field values
snippet:
type: string
description: snippet (summary) of the retrieved source
count:
description: number of result sources (ignoring page and pageSize)
type: integer
EntityList:
description: list of entities
type: object
properties:
entities:
type: array
items:
$ref: '#/definitions/Entity'
count:
type: integer
description: number of result entities (ignoring page and pageSize)
Entity:
type: object
required:
- id
- value
properties:
id:
type: integer
description: unique entity ID
value:
type: string
description: entity value
frequency:
type: integer
description: number of times the entity occurs in the result set
spread:
type: integer
description: number of distinct sources the entity occurs in in the result set
CRCList:
type: object
required:
- crcs
properties:
crcs:
type: array
items:
title: CRC
type: object
required:
- id
- relation
- frequency
- spread
properties:
id:
type: integer
description: unique entity ID
master:
type: string
description: entity value of the master concept
relation:
type: string
description: entity value of the relation
slave:
type: string
description: entity value of the slave concept
frequency:
type: integer
description: number of times the CRC occurs in the result set
spread:
type: integer
description: number of distinct sources the CRC occurs in in the result set
count:
type: integer
description: number of result CRCs (ignoring page and pageSize)
CRC:
type: object
required:
- relation
properties:
master:
type: string
description: entity value of the master concept
relation:
type: string
description: entity value of the relation
slave:
type: string
description: entity value of the slave concept
BlacklistList:
type: object
required: ["blacklists"]
properties:
blacklists:
type: array
items:
$ref: '#/definitions/BlacklistDetails'
BlacklistDetails:
type: object
required: ["id", "name"]
properties:
id:
type: integer
name:
type: string
description:
type: string
elements:
type: array
items:
type: string
DictionaryList:
type: object
required: ["dictionaries"]
properties:
dictionaries:
type: array
items:
$ref: '#/definitions/DictionaryDetails'
count:
type: integer
description: total number of dictionaries (ignoring page and pageSize)
DictionaryDetails:
type: object
required: ["id", "name"]
properties:
id:
type: integer
name:
type: string
language:
$ref: '#/definitions/LanguageCode'
description:
type: string
items:
type: array
items:
$ref: '#/definitions/DictionaryItemDetails'
DictionaryItemDetails:
type: object
required: ["id", "name", "uri"]
properties:
id:
type: integer
name:
description: display label
type: string
uri:
description: unique, domain-wide identifier for this Dictionary Item
type: string
language:
$ref: '#/definitions/LanguageCode'
terms:
type: array
items:
$ref: '#/definitions/DictionaryTermDetails'
DictionaryTermDetails:
type: object
required: ["id"]
example: { id: 123, string: "palm tree" }
properties:
id:
type: integer
language:
$ref: '#/definitions/LanguageCode'
string:
description: if this is a regular term, the term string value
type: string
regexp:
description: if this is a regular expression format term, the regular expression
type: string
replace:
description: if this is a regular expression format term, the replacement string
type: string
formatClass:
description: if this is a format term, the name of the format implementation class
type: string
formatParams:
description: if this is a format term, any additional parameters for the format implementation class
type: array
items:
type: string
MatchList:
type: object
required: ["matches"]
properties:
matches:
type: array
items:
$ref: '#/definitions/MatchListItem'
MatchListItem:
type: object
required: [ "id", "score" ]
properties:
id:
type: integer
score:
type: number
description: aggregated score for this match
partialCount:
type: integer
description: number of partially matched entities for this match
ordered:
type: boolean
format: integer
description: whether or not the matched entities appear in the term's order
negatedCount:
type: integer
description: number of entities
term:
type: object
title: MatchedTerm
required: ["id","item"]
properties:
id:
type: integer
string:
type: string
item:
title: MatchedItem
type: object
required: ["id", "uri", "name", "dictionary" ]
properties:
id:
type: integer
name:
type: string
uri:
type: string
dictionary:
title: MatchedDictionary
type: object
required: ["id", "name"]
properties:
id:
type: integer
name:
type: string
target:
title: MatchTarget
type: object
description: the matched piece of the source text
properties:
id:
type: integer
type:
type: string
enum: ["entity", "crc", "path", "sentence"]
sentenceId:
type: integer
sentence:
type: string
description: full text of the sentence where the match occurred
elements:
type: array
description: detailed overview of entity-level match results
items:
type: object
title: MatchedElements
required: ["partId", "literal", "score", "role", "matchedWords", "negated"]
properties:
partId:
type: integer
description: entity occurrence / part ID of the matched sentence part
literal:
type: string
description: literal string how this part appeared in the sentence
score:
type: number
description: entity-level score
role:
type: string
enum: ["concept", "relation", "pathRelevant" ]
description: role of this sentence part
matchedWords:
type: string
description: which words within the entity actually matched
negated:
type: boolean
format: integer
description: whether this sentence part is part of a negative context
entityId:
type: integer
description: entity ID, if this part corresponds to an entity
entity:
type: string
description: entity value, if this part corresponds to an entity
output:
type: string
description: format output, if this part corresponds to a matched format providing output
SentenceDetails:
type: object
required:
- id
- sourceId
- text
properties:
id:
description: sentence ID
type: integer
sourceId:
description: containing source ID
type: integer
text:
description: sentence text, optionally highlighted
type: string
parts:
description: entities in this sentence
type: array
items:
title: SentencePart
type: object
required:
- partId
- literal
- role
properties:
partId:
description: entity / part occurrence ID
type: integer
literal:
description: literal value of this part in the sentence
type: string
role:
description: role of this entity in the path
type: string
enum: ["concept", "relation", "pathRelevant"]
entityId:
description: unique entity ID, if this is not a non-relevant
type: integer
entity:
description: entity value, if this is not a non-relevant
type: string
stemId:
description: stem ID for this entity, if the domain is configured for stemming
type: string
stem:
description: stem value of this entity, if the domain is configured for stemming
type: string
attributes:
description: semantic attributes for this entity
type: array
items:
title: AttributeInfo
type: object
required: ["type", "level"]
properties:
type:
description: name of the attribute
type: string
level:
description: level at which the attribute applies
type: string
enum: ["path", "word"]
words:
description: if level="word", the actual words affected
type: string
properties:
description: attribute properties
type: object
HighlightSpec:
# TODO: move into proper hierarchy once swagger-ui supports it
description: The parameters needed for %iFind.Utils.Highlight
type: object
example:
{ "tag": "<b>", "limit":0, "name": "Highlighted"}
properties:
tag:
description: the tags used to enclose the highlighted segments
type: string
default: "<b>"
limit:
description: limit the segments get highlighted,check %iFind.Utils.Highlight() for details
type: integer
default: 0
name:
description: the alias name for the column containing highlighted text
type: string
default: "Highlighted"
RankSpec:
# TODO: move into proper hierarchy once swagger-ui supports it
description: The parameters needed for %iFind.Utils.Rank
type: object
example:
{ "name":"Rank" }
properties:
name:
description: the alias name for the column containing rank info
type: string
default: "Rank"
OptionSpec:
description: The option could be object which includes all the required parameters. However, you could still use "0","1","2","3","4" these simple strings for option for the legacy support
type: object
properties:
mode:
type: string
enum: ["0","1","2","3","4","*","normal","stemmed","decompounded","fuzzy","regex"]
description: the iFind search options. 0/normal search,1/stemmed search,2/decompunded search,3/fuzzy search,4/regex search, "*" indicates use the index setting
stemmer:
type: string
description: the stemming/decompounding class
arguments:
type: array
description: the arguments needed for initialize a stemming/decompounding class
items:
type: string
distance:
type: string
description: the fuzzy search threshold.
|
|
|
|
|
|
|
|
summary: | Adds a source to the domain tags: ["Sources"] parameters: - $ref: '#/parameters/domainParam' - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object required: ["reference", "text"] properties: reference: description: a string to be used for building the new record's external ID type: string text: description: the text to index type: string configuration: description: name of a valid configuration object to use or the two-letter ISO code for the language to use (if no such configuration exists) type: string example: en virtual: description: if true, the source will be added as a virtual one type: boolean default: 0 format: integer metadata: description: map of metadata field values to set for the document type: object responses: 200: description: Successful response schema: type: object required: ["id"] properties: id: description: source ID of the newly created record type: integer
summary: | Adds new elements to a given blacklist tags: ["Blacklists"] parameters: - $ref: '#/parameters/domainParam' - name: id in: path type: string description: ID of the blacklist to extend required: true - name: string in: path type: string description: element to add to the blacklist required: true - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: elements: description: if set, overrides what's passed in through the path parameter type: array example: [] items: type: string responses: 200: description: Successful response schema: type: object properties: added: description: number of elements added type: integer
summary: | Clears all entries for a given blacklist tags: ["Blacklists"] parameters: - $ref: '#/parameters/domainParam' - name: id in: path type: string description: ID of the blacklist to clear required: true responses: 200: description: Successful response schema: type: object properties: cleared: type: boolean format: integer
summary: | Creates a new blacklist tags: ["Blacklists"] parameters: - $ref: '#/parameters/domainParam' - name: name in: path description: name of the new blacklist required: true type: string - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: name: description: overrides what's passed in through the path parameter if set type: string description: type: string elements: type: array example: [] items: type: string responses: 200: description: Successful response schema: $ref: '#/definitions/BlacklistDetails'
summary: | Create a new dictionary tags: ["Dictionaries and Matching"] parameters: - $ref: '#/parameters/domainParam' - name: name description: name for the new dictionary in: path type: string required: true - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: name: description: if provided, overrides the path parameter type: string description: type: string language: description: default language for dictionary entries $ref: '#/definitions/LanguageCode' items: description: list of items to add (don't supply id values) type: array items: $ref: '#/definitions/DictionaryItemDetails' match: description: if set to true, the dictionary is immediately matched against the domain's sources type: boolean format: integer filter: description: if match=1, restricts the sources to be matched $ref: '#/definitions/Filter' responses: 200: description: Successful response schema: allOf: - $ref: '#/definitions/DictionaryDetails' - type: object properties: created: type: boolean format: integer default: 1 matched: type: boolean format: integer
summary: | Create new dictionary items tags: ["Dictionaries and Matching"] parameters: - $ref: '#/parameters/domainParam' - name: id description: ID of the dictionary to which to add the new item in: path type: string required: true - name: RequestBody description: JSON object with a list of query-specific arguments in: body required: true schema: type: object properties: dictionaryId: description: if provided, overrides the path parameter type: string items: description: list of items to add (don't supply id values) type: array items: $ref: '#/definitions/DictionaryItemDetails' match: description: if set to true, the dictionary is immediately matched against the domain's sources type: boolean format: integer filter: description: if match=1, restricts the sources to be matched $ref: '#/definitions/Filter' responses: 200: description: Successful response schema: title: AddItemsResult type: object properties: dictionary: type: object title: DictionaryDetails description: the dictionary these items were added to properties: id: type: integer name: type: string items: type: array items: allOf: - $ref: '#/definitions/DictionaryItemDetails' - type: object properties: error: description: the error message, if this item failed to get created type: string matched: type: boolean format: integer
Simplified version ofCreateDictionaryItems for HTTP POST requestssummary: | Create new dictionary items tags: ["Dictionaries and Matching"] parameters: - $ref: '#/parameters/domainParam' - name: RequestBody description: JSON object with a list of query-specific arguments in: body required: true schema: type: object required: ["dictionaryId", "items"] properties: dictionaryId: description: if provided, overrides the path parameter type: string items: description: list of items to add (don't supply id values) type: array items: $ref: '#/definitions/DictionaryItemDetails' match: description: if set to true, the dictionary is immediately matched against the domain's sources type: boolean format: integer filter: description: if match=1, restricts the sources to be matched $ref: '#/definitions/Filter' responses: 200: description: Successful response schema: title: AddItemsResult type: object properties: dictionary: type: object title: DictionaryDetails description: the dictionary these items were added to properties: id: type: integer name: type: string items: type: array items: allOf: - $ref: '#/definitions/DictionaryItemDetails' - type: object properties: error: description: the error message, if this item failed to get created type: string matched: type: boolean format: integer
summary: | Create new dictionary terms tags: ["Dictionaries and Matching"] parameters: - $ref: '#/parameters/domainParam' - name: id description: ID or URI of the dictionary item to which to add the new terms in: path type: string required: true - name: RequestBody description: JSON object with a list of query-specific arguments in: body required: true schema: type: object properties: dictionaryItemId: description: if provided, overrides the corresponding path parameter type: string terms: description: list of terms to add (don't supply id values). An array of strings will be interpreted as simple terms. type: array items: $ref: '#/definitions/DictionaryTermDetails' match: description: if set to true, the dictionary is immediately matched against the domain's sources type: boolean format: integer filter: description: if match=1, restricts the sources to be matched $ref: '#/definitions/Filter' responses: 200: description: Successful response schema: title: AddTermsResult type: object properties: item: type: object title: DictionaryItemDetails description: the dictionary item these terms were added to properties: id: type: integer name: type: string uri: type: string dictionary: type: object title: DictionaryDetails description: the dictionary these terms were added to properties: id: type: integer name: type: string terms: type: array items: allOf: - $ref: '#/definitions/DictionaryTermDetails' - type: object properties: error: description: the error message, if this term failed to get created type: string matched: type: boolean format: integer
summary: | Drops a given blacklist tags: ["Blacklists"] parameters: - $ref: '#/parameters/domainParam' - name: id in: path type: string description: ID of the blacklist to drop required: true responses: 200: description: Successful response schema: type: object properties: dropped: type: boolean format: integer
summary: | Drops a dictionary tags: ["Dictionaries and Matching"] parameters: - $ref: '#/parameters/domainParam' - name: id description: ID of the dictionary to drop in: path type: integer required: true responses: 200: description: Successful response schema: type: object properties: dropped: type: boolean format: integer
summary: | Drops a dictionary item tags: ["Dictionaries and Matching"] parameters: - $ref: '#/parameters/domainParam' - name: id description: ID or URI of the dictionary item to drop in: path type: integer required: true responses: 200: description: Successful response schema: type: object properties: dropped: type: boolean format: integer
summary: | Drops a dictionary term tags: ["Dictionaries and Matching"] parameters: - $ref: '#/parameters/domainParam' - name: id description: ID of the dictionary term to drop in: path type: integer required: true responses: 200: description: Successful response schema: type: object properties: dropped: type: boolean format: integer
summary: | Deletes a source from the domain tags: ["Sources"] parameters: - $ref: '#/parameters/domainParam' - name: source description: the source ID to drop in: path required: true type: integer - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: virtual: description: if set, the supplied source ID will be used to look up a virtual source type: boolean format: integer default: 0 responses: 200: description: Successful response schema: type: object required: - deleted properties: deleted: type: boolean format: integer
summary: | Retrieves a particular blacklist's contents tags: ["Blacklists"] parameters: - $ref: '#/parameters/domainParam' - name: id in: path type: integer description: ID of the blacklist being queried required: true responses: 200: description: Successful response schema: $ref: '#/definitions/BlacklistDetails'
summary: | Retrieves a list of available blacklists tags: ["Blacklists"] parameters: - $ref: '#/parameters/domainParam' - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: includeDetails: description: whether or not to retrieve blacklists' contents as well type: boolean format: integer includeCrossDomain: description: whether or not to include cross-domain blacklists type: boolean format: integer responses: 200: description: Successful response schema: $ref: '#/definitions/BlacklistList'
summary: | Retrieves the top CRCs for this domain tags: ["Paths and CRCs"] parameters: - $ref: '#/parameters/domainParam' - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: page: $ref: '#/definitions/PageNumber' pageSize: $ref: '#/definitions/PageSize' filter: $ref: '#/definitions/Filter' filterMode: $ref: '#/definitions/FilterMode' sortBy: description: criterion to use for retrieving the top entities type: string default: "domainDefault" example: "domainDefault" enum: ["frequency", "spread", "domainDefault"] includeCount: $ref: '#/definitions/IncludeCount' countOnly: $ref: '#/definitions/CountOnly' responses: 200: description: Successful response schema: $ref: '#/definitions/CRCList'
summary: | Retrieves the CRCs containing a designated entity tags: ["Paths and CRCs"] parameters: - $ref: '#/parameters/domainParam' - name: entity description: the entity to query for in: path required: true type: string - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: entity: description: if set, takes precedence over the path parameter type: array items: type: string default: "" page: $ref: '#/definitions/PageNumber' pageSize: $ref: '#/definitions/PageSize' filter: $ref: '#/definitions/Filter' filterMode: $ref: '#/definitions/FilterMode' positions: description: CRC positions to query type: array default: ["master", "relation", "slave"] example: ["master", "relation", "slave"] items: type: string enum: ["master", "relation", "slave"] actualFormOnly: type: boolean format: integer description: when this domain supports stemming, set to true to restrict to the supplied actual form only default: 0 includeCount: $ref: '#/definitions/IncludeCount' countOnly: $ref: '#/definitions/CountOnly' responses: 200: description: Successful response schema: $ref: '#/definitions/CRCList'
summary: | Retrieves all the configurations for this namespace, with basic info tags: ["Miscellaneous"] parameters: - name: RequestBody description: additional parameters to configure this query in: body required: false schema: type: object properties: includeUserDictionaryContents: type: boolean description: Whether or not to include user dictionary contents default: false format: integer responses: 200: description: Successful response schema: $ref: '#/definitions/ConfigurationList'
summary: | Retrieves a list of available dictionaries tags: ["Dictionaries and Matching"] parameters: - $ref: '#/parameters/domainParam' - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: includeItems: description: whether or not to include item and term details as well type: boolean format: integer includeCount: $ref: '#/definitions/IncludeCount' countOnly: $ref: '#/definitions/CountOnly' responses: 200: description: Successful response schema: $ref: '#/definitions/DictionaryList'
summary: | Retrieves the detailed contents for a given Dictionary tags: ["Dictionaries and Matching"] parameters: - $ref: '#/parameters/domainParam' - name: id description: ID of the dictionary to retrieve in: path type: integer required: true responses: 200: description: Successful response schema: $ref: '#/definitions/DictionaryDetails'
summary: | Retrieves the detailed contents for a given Dictionary Item tags: ["Dictionaries and Matching"] parameters: - $ref: '#/parameters/domainParam' - name: id description: ID or URI of the dictionary item to retrieve in: path type: integer required: true responses: 200: description: Successful response schema: allOf: - $ref: '#/definitions/DictionaryItemDetails' - type: object properties: dictionary: type: object properties: id: type: integer name: type: string
summary: | Retrieve more detailed information about an individual domain tags: ["Miscellaneous"] parameters: - $ref: '#/parameters/domainParam' responses: 200: description: Successful response schema: $ref: '#/definitions/DomainDetails'
summary: | Retrieves all the domains for this namespace, with basic info tags: ["Miscellaneous"] responses: 200: description: Successful response schema: $ref: '#/definitions/DomainList'
summary: | Retrieves the top entities for this domain tags: ["Entities"] parameters: - $ref: '#/parameters/domainParam' - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: page: $ref: '#/definitions/PageNumber' pageSize: $ref: '#/definitions/PageSize' filter: $ref: '#/definitions/Filter' filterMode: $ref: '#/definitions/FilterMode' blacklists: $ref: '#/definitions/Blacklists' sortBy: description: criterion to use for retrieving the top entities type: string default: "domainDefault" example: "domainDefault" enum: ["frequency", "spread", "domainDefault", "dominance", "bm25", "tfidf"] useStems: description: | retrieve stems rather than entities. (only available when the domain has stemming enabled and for certain sortBy values) type: integer default: 0 format: integer role: description: whether to retrieve top concepts, relationships or both (only available for certain sortBy values) type: string default: "concept" enum: ["concept", "relation", "any"] includeMetrics: description: additional metrics to retrieve, on top of what is automatically retrieved based on the sortBy value type: array default: [] items: type: string enum: ["frequency", "spread", "dominance", "tfidf"] includeCount: $ref: '#/definitions/IncludeCount' countOnly: $ref: '#/definitions/CountOnly' responses: 200: description: Successful response schema: title: EntityList type: object properties: entities: type: array items: title: Entity type: object required: - id - value properties: id: type: integer description: unique entity ID value: type: string description: entity value frequency: type: integer description: number of times the entity occurs in the result set spread: type: integer description: number of distinct sources the entity occurs in in the result set dominance: type: number description: relevance of the entity in this result set tfidf: type: number description: TFIDF-based metric expressing relevance of the entity in this result set bm25: type: number description: BM25-based metric expressing relevance of the entity in this result set count: type: integer description: total number of entities in this domain (if RequestBody.includeCount is true, ignoring page and pageSize)
summary: | Retrieves details for the supplied entity tags: ["Entities"] parameters: - $ref: '#/parameters/domainParam' - name: entity description: the entity whose details need to be returned in: path required: true type: string - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: entity: description: if set, overrides the value of the path parameter type: string default: "" filter: description: if set, restricts the dataset on which metrics should be based $ref: '#/definitions/Filter' useStems: description: only available when the domain has stemming enabled type: boolean default: 0 format: integer roles: description: roles for which the metrics need to be retrieved type: array default: ["concept", "relation", "any"] example: ["concept", "relation", "any"] items: type: string enum: ["concept", "relation", "any"] includeMetrics: description: metrics to retrieve type: array default: ["frequency", "spread", "tfidf"] example: ["frequency", "spread", "tfidf"] items: type: string enum: ["frequency", "spread", "tfidf"] responses: 200: description: Successful response schema: title: EntityDetails type: object required: - id - value properties: id: type: integer description: unique entity ID value: type: string description: entity value metricsAsConcept: type: object properties: frequency: type: integer description: number of times the entity occurs in the result set spread: type: integer description: number of distinct sources the entity occurs in in the result set tfidf: type: number description: TFIDF-based metric expressing relevance of the entity in this result set metricsAsRelation: type: object properties: frequency: type: integer description: number of times the entity occurs in the result set spread: type: integer description: number of distinct sources the entity occurs in in the result set tfidf: type: number description: TFIDF-based metric expressing relevance of the entity in this result set metricsAsAny: type: object properties: frequency: type: integer description: number of times the entity occurs in the result set spread: type: integer description: number of distinct sources the entity occurs in in the result set tfidf: type: number description: TFIDF-based metric expressing relevance of the entity in this result set
summary: | Retrieves all dictionary matches for a dictionary item tags: ["Dictionaries and Matching"] parameters: - $ref: '#/parameters/domainParam' - name: id description: the dictionary item ID or URI to query for in: path required: true type: integer - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: page: $ref: '#/definitions/PageNumber' pageSize: $ref: '#/definitions/PageSize' filter: $ref: '#/definitions/Filter' description: optionally filters the results to those matches in sources selected by this filter matchFirst: description: ensures the domain is matched against the latest dictionaries before retrieving results type: boolean format: integer default: 1 includeDictionaryDetails: description: whether or not to dictionary details as well type: boolean format: integer default: 1 includeMatchDetails: description: whether or not to entity-level match details as well type: boolean format: integer default: 0 includeSnippets: description: whether or not to include the text of the matched sentence type: boolean format: integer default: 1 highlight: $ref: '#/definitions/Highlighting' responses: 200: description: Successful response schema: $ref: '#/definitions/MatchList'
summary: | Retrieves all dictionary matches for a given source tags: ["Dictionaries and Matching"] parameters: - $ref: '#/parameters/domainParam' - name: id description: the source ID to query for in: path required: true type: integer - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: page: $ref: '#/definitions/PageNumber' pageSize: $ref: '#/definitions/PageSize' matchFirst: description: ensures this source is matched against the latest dictionaries before retrieving results type: boolean format: integer default: 1 dictionaries: description: if set, limits results to these dictionary IDs default: [] type: array items: type: integer includeDictionaryDetails: description: whether or not to retrieve dictionary details as well type: boolean format: integer default: 1 includeMatchDetails: description: whether or not to retrieve entity-level match details as well type: boolean format: integer default: 0 includeSnippets: description: whether or not to include the text of the matched sentence type: boolean format: integer default: 1 highlight: $ref: '#/definitions/Highlighting' responses: 200: description: Successful response schema: $ref: '#/definitions/MatchList'
summary: | Retrieves the paths containing a designated entity tags: ["Paths and CRCs"] parameters: - $ref: '#/parameters/domainParam' - name: entity description: the entity to query for in: path required: true type: string - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: entity: description: if set, takes precedence over the path parameter type: array items: type: string default: "" page: $ref: '#/definitions/PageNumber' pageSize: $ref: '#/definitions/PageSize' filter: $ref: '#/definitions/Filter' includeDetails: description: whether or not to include details on the entities for each path type: boolean default: 1 format: integer actualFormOnly: type: boolean format: integer description: when this domain supports stemming, set to true to restrict to the supplied actual form only default: 0 setOperation: type: string enum: ["union", "intersect"] description: when supplying multiple entities, controls how the results for each entity should be combined includeCount: $ref: '#/definitions/IncludeCount' countOnly: $ref: '#/definitions/CountOnly' responses: 200: description: Successful response schema: title: PathList type: object properties: paths: type: array items: title: Path properties: id: description: path ID type: integer entities: description: entities in this path type: array items: title: PathEntity type: object required: - id - entity properties: id: description: unique entity ID type: integer entity: description: entity value type: string partId: description: entity occurrence ID type: integer role: description: role of this entity in the path type: string enum: ["concept", "relation", "pathRelevant"] stemId: description: stem ID for this entity, if the domain is configured for stemming type: integer stem: description: stem value of this entity, if the domain is configured for stemming type: string attributes: description: semantic attributes for this entity type: array items: title: AttributeInfo type: object required: ["type", "level"] properties: type: description: name of the attribute type: string level: description: level at which the attribute applies type: string enum: ["path", "word"] words: description: if level="word", the actual words affected type: string properties: description: attribute properties type: object count: description: total number of paths, ignoring page and pageSize type: integer
summary: | Retrieves entities related to a seed entity based on proximity or direct relationships tags: ["Entities"] parameters: - $ref: '#/parameters/domainParam' - name: entity description: the seed entity to find related entities for in: path required: true type: string - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: entity: description: if set, overrides value of path parameter type: string default: "" example: "" page: $ref: '#/definitions/PageNumber' pageSize: $ref: '#/definitions/PageSize' filter: $ref: '#/definitions/Filter' filterMode: $ref: '#/definitions/FilterMode' blacklists: $ref: '#/definitions/Blacklists' sortBy: description: criterion to use for retrieving the related entities type: string default: "proximity" example: "proximity" enum: ["proximity", "frequency", "spread"] includeCount: $ref: '#/definitions/IncludeCount' countOnly: $ref: '#/definitions/CountOnly' responses: 200: description: Successful response schema: $ref: '#/definitions/EntityList'
summary: | Retrieves the details for a particular sentence tags: ["Sentences"] parameters: - $ref: '#/parameters/domainParam' - name: id description: the sentence ID to query for in: path required: true type: integer - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: highlight: $ref: '#/definitions/Highlighting' virtualSourceId: description: if set, the sentence will be looked up in the context of this virtual source type: integer responses: 200: description: Successful response schema: $ref: '#/definitions/SentenceDetails'
summary: | Retrieves the sentences containing a given entity tags: ["Sentences"] parameters: - $ref: '#/parameters/domainParam' - name: entity description: the entity to query for in: path required: true type: string - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: entity: description: if set, takes precedence over the corresponding path parameter type: array items: type: string default: "" page: $ref: '#/definitions/PageNumber' pageSize: $ref: '#/definitions/PageSize' filter: $ref: '#/definitions/Filter' highlight: $ref: '#/definitions/Highlighting' includeDetails: description: whether or not to include details on the entities for each sentence type: boolean default: 1 format: integer actualFormOnly: type: boolean format: integer description: when this domain supports stemming, set to true to restrict to the supplied actual form only default: 0 setOperation: type: string enum: ["union", "intersect"] description: when supplying multiple entities, controls how the results for each entity should be combined includeCount: $ref: '#/definitions/IncludeCount' countOnly: $ref: '#/definitions/CountOnly' responses: 200: description: Successful response schema: title: SentenceList type: object required: ["sentences"] properties: sentences: type: array items: $ref: '#/definitions/SentenceDetails' count: description: total number of paths, ignoring page and pageSize (if RequestBody.includeCount is set) type: integer
summary: | Retrieves entities similar to a seed string tags: ["Entities"] parameters: - $ref: '#/parameters/domainParam' - name: string description: the seed string to find similar entities for in: path required: true type: string - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: string: description: if set, overrides value of path parameter type: string default: "" example: "" page: $ref: '#/definitions/PageNumber' pageSize: $ref: '#/definitions/PageSize' filter: $ref: '#/definitions/Filter' filterMode: $ref: '#/definitions/FilterMode' blacklists: $ref: '#/definitions/Blacklists' type: description: | method to calculate / retrieve similar entities. ("ngrams" requires the domain to be configured for it) type: string default: "domainDefault" example: "domainDefault" enum: ["domainDefault", "parts", "ngrams", "words"] useStems: description: retrieve stems rather than entities. (only available when the domain has stemming enabled and for certain sortBy values) type: boolean default: 0 format: integer role: description: whether to retrieve top concepts, relationships or both (only available for certain sortBy values) type: string default: "any" example: "any" enum: ["concept", "relation", "any"] includeCount: $ref: '#/definitions/IncludeCount' countOnly: $ref: '#/definitions/CountOnly' responses: 200: description: Successful response schema: $ref: '#/definitions/EntityList'
summary: | Retrieves all sources similar to a seed source tags: ["Sources"] parameters: - $ref: '#/parameters/domainParam' - $ref: '#/parameters/sourceParam' - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: page: $ref: '#/definitions/PageNumber' pageSize: $ref: '#/definitions/PageSize' filter: $ref: '#/definitions/Filter' highlight: $ref: '#/definitions/Highlighting' algorithm: type: string enum: ["simple", "dominantEntities"] description: algorithm to use for calculating similar entities default: "simple" parameters: type: array items: type: string description: additional parameters to tune the algorithm default: [] includeMetadata: description: whether or not to include metadata for each retrieved source type: boolean default: 1 format: integer includeSnippets: description: if set to a nonzero value, a snippet of the designated length (in sentences) will be retrieved for each source type: integer default: {{{SNIPPETSIZE}}} responses: 200: description: Successful response schema: allOf: - $ref: '#/definitions/SourceList' - type: object properties: score: type: number description: score expressing the similarity between this record and the seed document percentageMatched: type: number percentageNew: type: number numberOfEntitiesInRefSource: type: integer numberOfEntitiesInCommon: type: integer numberOfEntitiesInThisSource: type: integer
summary: | Retrieves the details of a particular source tags: ["Sources"] parameters: - $ref: '#/parameters/domainParam' - $ref: '#/parameters/sourceParam' - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: includeMetadata: description: whether or not to include metadata for the designated source type: boolean default: 1 format: integer includeText: description: whether or not to include the full source text in the result type: boolean default: 1 format: integer summarize: description: if set, the text returned will be a summary of the full contents, measuring this many sentences type: number virtual: description: if set to true, the source ID will be considered to refer to a virtual source type: boolean default: 0 format: integer highlight: $ref: '#/definitions/Highlighting' responses: 200: description: Successful response schema: title: Source type: object properties: text: type: string description: textual contents (optionally summarized) of this source metadata: type: object description: metadata map for this source virtual: type: boolean format: integer description: whether or not this is a virtual source
summary: | Retrieves all sources matching the supplied filter tags: ["Sources"] parameters: - $ref: '#/parameters/domainParam' - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: page: $ref: '#/definitions/PageNumber' pageSize: $ref: '#/definitions/PageSize' filter: $ref: '#/definitions/Filter' highlight: $ref: '#/definitions/Highlighting' includeMetadata: description: whether or not to include metadata for each retrieved source type: boolean default: 1 format: integer includeSnippets: description: if set to a nonzero value, a snippet of the designated length (in sentences) will be retrieved for each source type: integer default: {{{SNIPPETSIZE}}} includeCount: $ref: '#/definitions/IncludeCount' countOnly: $ref: '#/definitions/CountOnly' responses: 200: description: Successful response schema: $ref: '#/definitions/SourceList'
summary: | Retrieves all sources containing the supplied CRC tags: ["Sources"] parameters: - $ref: '#/parameters/domainParam' - name: crc in: path description: CRC to look for, as a colon-separated sequence of master, relation and slave. If supplied in the request object, that value will take precedence over the path parameter type: string required: true #example: john:likes:bananas - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: crc: type: array items: $ref: '#/definitions/CRC' description: | if supplied, overwrites the value of the "crc" path parameter default: "" page: $ref: '#/definitions/PageNumber' pageSize: $ref: '#/definitions/PageSize' filter: $ref: '#/definitions/Filter' highlight: $ref: '#/definitions/Highlighting' includeMetadata: description: whether or not to include metadata for each retrieved source type: boolean default: 1 format: integer includeSnippets: description: if set to true, a snippet made up of all the sentences containing the designated CRCs will be retrieved for each source type: boolean default: 1 format: integer setOperation: type: string enum: ["union", "intersect"] description: when supplying multiple entities, controls how the results for each entity should be combined includeCount: $ref: '#/definitions/IncludeCount' countOnly: $ref: '#/definitions/CountOnly' responses: 200: description: Successful response schema: $ref: '#/definitions/SourceList'
summary: | Retrieves all sources containing the supplied entity tags: ["Sources"] parameters: - $ref: '#/parameters/domainParam' - name: entity in: path description: entity to look for. If supplied in the request object, that value will take precedence over the path parameter type: string required: true - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: entity: type: array items: type: string description: | if supplied, overwrites the value of the "entity" path parameter default: "" page: $ref: '#/definitions/PageNumber' pageSize: $ref: '#/definitions/PageSize' filter: $ref: '#/definitions/Filter' highlight: $ref: '#/definitions/Highlighting' includeMetadata: description: whether or not to include metadata for each retrieved source type: boolean default: 1 format: integer includeSnippets: description: if set to true, a snippet made up of all sentences containing the designated entities will be retrieved for each source type: boolean default: 1 format: integer actualFormOnly: type: boolean format: integer description: when this domain supports stemming, set to true to restrict to the supplied actual form only default: 0 setOperation: type: string enum: ["union", "intersect"] description: when supplying multiple entities, controls how the results for each entity should be combined includeCount: $ref: '#/definitions/IncludeCount' countOnly: $ref: '#/definitions/CountOnly' responses: 200: description: Successful response schema: $ref: '#/definitions/SourceList'
summary: | Highlights the supplied text tags: ["Miscellaneous"] parameters: - $ref: '#/parameters/domainParam' - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object required: ["highlight", "text"] properties: text: description: the text to highlight example: "This text is in urgent need of fancy markup!" type: string configuration: description: name of a valid configuration object to use or the two-letter ISO code for the language to use (if no such configuration exists) type: string example: en highlight: description: highlighting specification $ref: '#/definitions/Highlighting' example: [ { role: "concept", style: "[]" }, { role: "relation", style: "{}" }] responses: 200: description: Successful response schema: type: object required: ["text"] properties: text: description: the highlighted text type: string
summary: | Highlights the supplied text tags: ["Miscellaneous"] parameters: - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object required: ["highlight", "text"] properties: text: description: the text to highlight example: "This text is in urgent need of fancy markup!" type: string configuration: description: name of a valid configuration object to use or the two-letter ISO code for the language to use (if no such configuration exists) type: string example: en highlight: description: highlighting specification $ref: '#/definitions/Highlighting' example: [ { role: "concept", style: "[]" }, { role: "relation", style: "{}" }] responses: 200: description: Successful response schema: type: object required: ["text"] properties: text: description: the highlighted text type: string
summary: | Indexes the supplied text and returns concepts, relations and CRCs tags: ["Miscellaneous"] parameters: - $ref: '#/parameters/domainParam' - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object required: ["highlight", "text"] properties: text: description: the text to index example: "This text is in urgent need of fancy markup!" type: string configuration: description: name of a valid configuration object to use or the two-letter ISO code for the language to use (if no such configuration exists) type: string example: en summarize: description: if set to a nonzero value, the text returned will be a summary of the full contents, measuring this many sentences type: number default: 0 highlight: description: highlighting specification $ref: '#/definitions/Highlighting' example: [ { role: "concept", style: "[]" }, { role: "relation", style: "{}" }] includeMatches: description: whether or not to retrieve dictionary matches for the indexed record type: boolean format: integer default: 0 dictionaries: description: if set, limits results to these dictionary IDs default: [] type: array items: type: integer includeDictionaryDetails: description: whether or not to retrieve dictionary details as well type: boolean format: integer default: 1 includeMatchDetails: description: whether or not to entity-level match details as well type: boolean format: integer default: 0 responses: 200: description: Successful response schema: type: object required: ["text"] properties: text: description: the highlighted text type: string concepts: description: list of concepts for this text type: array items: type: object properties: value: type: string frequency: type: integer dominance: type: integer relations: description: list of relations for this text type: array items: type: object properties: value: type: string frequency: type: integer dominance: type: integer matches: description: list of dictionary matches for this text type: array items: $ref: '#/definitions/MatchListItem'
summary: | Matches all sources against the current dictionary contents tags: ["Dictionaries and Matching"] parameters: - $ref: '#/parameters/domainParam' - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: filter: $ref: '#/definitions/Filter' description: optionally limits the operation to those sources selected by this filter dictionaries: description: if set, limits the operation to these dictionary IDs default: [] type: array items: type: integer responses: 200: description: Successful response schema: type: object properties: matched: type: boolean format: integer default: 1
summary: | Matches a particular source against the current dictionary contents tags: ["Dictionaries and Matching"] parameters: - $ref: '#/parameters/domainParam' - $ref: '#/parameters/sourceParam' - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: dictionaries: description: if set, limits the operation to these dictionary IDs default: [] type: array items: type: integer responses: 200: description: Successful response schema: type: object properties: matched: type: boolean format: integer default: 1
summary: | Removes elements from a given blacklist tags: ["Blacklists"] parameters: - $ref: '#/parameters/domainParam' - name: id in: path type: string description: ID of the blacklist to modify required: true - name: string in: path type: string description: element to remove from the blacklist required: true - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: elements: description: if set, overrides what's passed in through the path parameter type: array example: [] items: type: string responses: 200: description: Successful response schema: type: object properties: removed: description: number of elements removed type: integer
summary: | Search the given iFind index in the given table tags: ["iFind"] parameters: - $ref: '#/parameters/tableParam' - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: query: description: This is the only necessary parameter with no default value. The search terms to query against the iFind index. type: string index: description: the iFind index would be searched against, if you don't specify it, the first found iFind index would be used . type: string option: $ref: '#/definitions/OptionSpec' distance: description: only valid when option is fuzzy search (when option is 3) type: string example: "3" language: description: iKnow-supported language model to apply, for example "en" type: string includeText: description: whether the returned columns should include the column beging indexed by 'index' type: integer default: 0 enum: [0, 1] columns: description: specify the columns which also needed to be returned. For example, ["column1","column2"] type: array example: [] items: type: string highlightSpec: $ref: '#/definitions/HighlightSpec' description: the parameters needed for Highlight rankSpec: $ref: '#/definitions/RankSpec' description: the parameters needed for Rank where: description: the valid SQL logical condition statement. For example, "column1 = ? AND column2 = ?" type: string responses: 200: description: Successful response schema: type: object properties: rows: type: array default: [] items: type: object
summary: | Registers metadata values for a given source tags: ["Sources"] parameters: - $ref: '#/parameters/domainParam' - name: source description: the source ID whose metadata needs updating in: path required: true type: integer - name: RequestBody description: JSON object with a list of query-specific arguments in: body schema: type: object properties: metadata: description: map of metadata field values to set for this source type: object responses: 200: description: Successful response schema: type: object required: - updated properties: updated: type: boolean format: integer