Manage data and workflows and search and discovery

visual_investigator

2024.09

2024.10

The SAS Visual Investigator Search and Discovery API provides access to real-time exploration and visualization of the data in SAS Visual Investigator.

Search and Discovery

2024.07

2024.08

2024.03

2023.03

2023.10

Viya_35

The VI Search and Discovery API provides access to real-time exploration and visualization of the data in Visual Investigator.

Imports the configuration for multiple types. This is intended to be used for moving the configuration between systems and as such there are no version numbers in the request and any existing configuration will be overwritten. If the new configuration contains breaking changes, such as the field type or events configuration has changed, the changes are saved but also require the data to be re-indexed to take effect. A localized message is included in the response if this is the case. The /admin/indices resource can be used to re-index the data.

An example of the request and response for /admin/config.

An example of the request and response for /admin/config/types/{type}.

An example of event configuration that extracts at most one event per array entry in the "old_addresses" field based on the root path. As the field specifiers are not delimited by /, each event is populated from the inner fields of the corresponding array entry. Since the tokenized text for the interval values refer to a single field, those fields must be of type date and contain valid ISO formatted date/time values. As "state" is a required field, events are extracted only if the array entry has a value for that field as well as either a valid GeoJSON value in the "location" field or values in both the "date_from" and "date_to" fields. The absence of a "city" field value causes that token to be removed from the description without being replaced with a value.

An example of event configuration that extracts a single event based on an object's top-level "lon", "lat", "city" and "state" fields. As there are no required fields defined, the event is extracted only if an object contains a numerical value in the "lon" field constituting a valid longitude and a numerical value in the "lat" field constituting a valid latitude value. The absence of "city" or "state" field values causes those tokens to be removed from the description without being replaced with a value.

An example of event configuration that shows how to mix absolute and relative paths in field specifiers. The example is based on an object with 4 levels of sub-objects (none of which are arrays); "level1" is a top-level field in the object containing a "level2" field and so on. In this case, a single event is extracted from the "level3" sub-object comprised of the "level3_date" time value and a description based on the "level3_text" field in this sub-object, the "level2_text" field from this sub-object's parent ("level2") and the "level4_text" from this sub-object's child ("level4"). Given that pointTimestamp refers to a single field, that field must be of type date. As there are required fields, the event is extracted only if these have values as well as "level3_date" having a value.

An example of event configuration that extracts a single event based on an object's top-level "opendate", "account_holder_forename", and "account_holder_surname" fields. Given that pointTimestamp refers to a single field, that field must be of type date thereby containing an ISO formatted date/time value. As there are no required fields defined, the event is extracted only if an object has a value for "opendate". The absence of "account_holder_forename" or "account_holder_surname" field values causes those tokens to be removed from the description without being replaced with a value.

An example of the configuration for the date range facet based on a report date. In addition to the administrator defined ranges, the filter section suggests that clients are allowed to define their own range filters but not their own filter on an exact value.

An example of the configuration for the numerical range facet based on transaction amounts. In addition to the administrator defined ranges, the filter section suggests that clients are allowed to define their own range filters.

An example of the configuration for the terms facet that is based on the city field show casing how to order results highest count first.

An example of the configuration for the type facet show casing how to sort results by alphabetical order.

An example of the graph configuration that includes the specified fields in graph responses.

An example of the label configuration that generates the templated label from the values in the specified fields.

An example of the summary configuration that includes specific fields to return and well as a field to generate highlighting for when its content matches a search query.

An example of the table configuration that includes the specified fields.

An example of the text analytics configuration that includes the subject and body fields in the corpus and uses the from, to and cc fields for the Sankey diagrams.

The request and response for /admin/config when importing and exporting a configuration between systems.

Whether to validate the configuration and check for breaking changes without importing it.

validateOnly

Whether to wait for any index-related operations to be applied prior to the response being returned.

waitForRefresh

The request is malformed or contains invalid parameter values.

An example URL including the base path for this API.

Import configuration

The response from /analytics/{jobId}/categories containing the categories of text analytics results that are available at a given exploration level.

analyticsCategories

The optional list of terms, phrases, topics, and entities to exclude from the analytics results keyed by category.

analyticsExcludesMap

The exploration level within the text analytics results.

analyticsExplorationLevel

The request to /analytics/{jobId}/results and /analytics/{jobId}/categories to retrieve the text analytics results and categories of result, respectively at a given exploration level

analyticsExplore

The response from /analytics/{jobId}/identities containing the identities for the person, organization, and location entities that were resolved by the text analytics job.

analyticsIdentities

The identities keyed by category (person, organization, or location). Resolved entity results matching any of the aliases will be grouped under the respective identity name.

analyticsIdentitiesMap

The identity for a person, organization, or location entity that was resolved by the text analytics job.

analyticsIdentity

An alias for a person, organization, or location entity that was resolved by the text analytics job.

analyticsIdentityAlias

The response from /analytics and /analytics/{jobId} containing the identifier, state, and parameters of a scheduled text analytics job. The job analyses unstructured text in the matching search results to extract significant terms, phrases, and topics as well as resolve named person, organization and location entities.

analyticsJob

A locale that is supported for text analytics. It is returned in a collection from /analytics/locales.

analyticsLocale

A collection of analytics locale representations.

analyticsLocaleCollection

The request to /analytics to initiate a new text analytics job. The job analyses unstructured text in the matching search results to extract significant terms, phrases, and topics as well as resolve named person, organization, and location entities.

analyticsRequest

The response from /analytics/{jobId}/results containing the text analytics results that are available at a given exploration level

analyticsResults

analyticsResult

The response from /analytics/{jobId}/sankeyDiagrams containing a Sankey diagram generated from the text analytics results at the specified exploration level.

analyticsSankeyDiagram

The request to /analytics/{jobId}/sankeyDiagrams to generate a Sankey diagram from the text analytics results at the specified exploration level.

analyticsSankeyDiagramRequest

analyticsSankeyLink

analyticsSankeyNode

A supported analyzer for analyzing text at index or search time. Returned in a collection from /admin/config/analyzers.

analyzer

analyzerCollection

The list of links to top-level resources and operations available from the root of the API.

This is a base schema used to define paginated collections of resources. This base schema is extended by other schemas in APIs by adding an "items" array property. These extensions define the application/vnd.sas.collection media type (version 2).

baseCollection2

An edge within the context of a request to /centrality for calculating centrality metrics for the objects on a network.

centralityEdge

The different centrality values for an object on the network.

centralityMetrics

The response from /centrality representing the centrality metrics for the objects on a network.

centralityMetricsCollection

The request to /centrality for calculating the centrality metrics for the objects on a network. The network is represented by a collection of edges, that is, the relationships between the objects.

centralityNetwork

The part of the response from /highlighting that groups highlighting snippets by child entity.

childEntityHighlighting

The part of the request to /highlighting that specifies the paging parameters for each child entity.

childEntityHighlightingParameters

The part of the response from /highlighting that captures highlighting snippets for a single child object.

childObjectHighlighting

configuration

An edge within the context of the Network visualization. An edge represents a relationship between two entity objects or between a resolved entity object and one of its contributing objects. Note the fields property is returned only from /graphs/edges.

edge

edgeCollection

The identifier for a vertex on one end of an edge.

endpoint

Describes the fields to retrieve for a given entity.

entityFields

A collection of properties that determine the style for an entity object

entityStyle

error2

An event within the context of the Map and Time Line visualizations

event

The different filter types that can be applied to narrow or drill down into the search results. See specific filter definitions for more details.

filter

This filter combines two or more filter objects using a Boolean AND operation thereby creating the intersection of their individual search results

filterTypeAnd

Filters objects based on geo data in the form of events. Objects containing a geo event whose location intersects with the specified bounded box will be included in the search results.

filterTypeBox

Filters objects by values in date fields. Objects containing a date value in the specified field within the given range will be included in the search results.

filterTypeDateRange

This filter applies the Boolean NOT operation to another filter thereby producing the opposite search results of the contained filter.

filterTypeNot

This filter combines two or more filter objects using a Boolean OR operation thereby creating the union of their individual search results

filterTypeOr

Filters objects based on geo data in the form of events. Objects containing a geo event whose location intersects with the specified polygon will be included in the search results.

filterTypePolygon

Filters objects based on the given query. Objects matching the query will be included in the search results.

filterTypeQuery

Filters objects based on geo data in the form of events. Objects containing a geo event whose location intersects with the specified circle will be included in the search results.

filterTypeRadius

Filters objects by values in numerical fields. Objects containing a numerical value in the specified field within the given range will be included in the search results.

filterTypeRange

Filters objects based on geo data in the form of events. Objects containing a geo event whose location relates to the specified GeoJSON shape will be included in the search results.

filterTypeShape

Filters objects by values in text fields. Only objects containing an exact match for one of the specified terms in the specified field will be included in the search results.

filterTypeTerms

Filters objects by their type. Objects of the named types will be included in the search results.

filterTypeType

A GeoJSON feature in the context of the Map visualization

geoJsonFeature

The GeoJSON feature collection returned as part of the Map visualization when the results are not clustered.

geoJsonFeatureCollection

The details about the events at this map location.

geoJsonFeatureProperties

A GeoJSON shape for use in the shape filter.

geoJsonShape

A collection of GeoJSON shape representations.

geoJsonShapeCollection

The response from /graphs and /traversals in relation to the Network visualization. In the network, objects are represented by vertices and the relationships between them are represented by edges.

graph

The total number of vertices and edges in the graph

graphCounts

The request to /graphs for obtaining the Network visualization. In the network, objects are represented by vertices and the relationships between them are represented by edges.

graphRequest

The response from /highlighting containing highlighting snippets for a single object based on a given query.

highlighting

The request to /highlighting for generating highlighting snippets for a single object based on a given query

highlightingRequest

The response from /admin/indices/{type} when requesting information about the index for a single entity

index

indexCollection

indicatorIcon

A link to a related operation or resource.

link

maskedFieldConfiguration

The identifier of a single object used in many of the requests and responses.

objectIdentifier

The request to /admin/operations to perform an administration-related operation

operationRequest

The parameters for the refresh configuration operation

operationRequestParametersForRefreshConfiguration

The parameters for the make index searchable operation.

operationRequestParametersForMakeIndexSearchable

The response from a request to /admin/operations to perform an administration-related operation.

operationResponse

A path within the context of the Network visualization. A path is a finite sequence of relationships (edges) connecting a sequence of objects (vertices) in the Network visualization.

path

pathCollection

The request to /paths when searching for matching paths from one or more start objects. Use the type and id properties to identify a single start object, or use the types and query properties to identify one or more start objects.

pathsRequest

The criteria for the next level of the path search.

pathsRequestNextLevel

The different query types that can be used to search for objects. See specific query definitions for more details.

query

The request to perform an action on data specified by a query.

queryRequest

This query combines two or more query objects using a Boolean AND operation thereby creating the intersection of their individual search results.

queryTypeAnd

This query allows resolved entity objects to be searched by their compound values (globally unique text fragments based on the values extracted from the resolved entity's contributing objects). Resolved entity objects containing one or more matching compounds will be included in the search results. These values are not expected to be known by users/clients but rather they can be extracted from the results of an earlier free-text or geospatial search.

queryTypeCompound

This query allows objects to be searched by their type and identifier. Objects with matching types and identifiers will be included in the search results. These values are not necessarily expected to be known by users/clients but rather they can be extracted from an earlier search result.

queryTypeObject

This query combines two or more query objects using a Boolean OR operation thereby creating the union of their individual search results.

queryTypeOr

This is the main query object and represents a free text query in a specified query language. Objects matching one or more query terms will be included in the search results.

queryTypeText

The request to /relatedObjects when searching for paths between start and end objects.

relatedObjectsRequest

A collection of properties that determine the style for a relationship.

relationshipStyle

The request to /searches when performing a search including the object types to search, the query, filter, and selection criteria, as well as which visualizations to return

searchRequest

The response from /searches when performing a search including the various visualizations that can be returned.

searchResponse

The criteria by which search results are marked as selected. In order to perform certain tasks within SAS Visual Investigator, such as adding search results to a workspace or expanding nodes in a network, the search results must first be selected. Manually selecting large numbers of results can be tedious and therefore SAND allows manual selection to be combined with query-based selection (all matching objects are marked as selected) and facet-based selection (all objects matching any of the filters will be marked as selected). The filter parameter represents the facet-based selection; the include parameter represents the manual and query based selections; the exclude parameter represents the manual and query based de-selections. All parameters are optional such that selections can be made by filter only, by include query only, or by object references and compound values. Objects matching either the filter or the include parameter will be selected as long as they do not match the exclude parameter.

selection

The query-based selection as well as the object references and compound values representing the manually included or excluded hits.

Name	Type	Required	Description
validateOnly	boolean	false	Whether to validate the configuration and check for breaking changes without importing it. Default: false
waitForRefresh	boolean	false	Whether to wait for any index-related operations to be applied prior to the response being returned. Default: false

Name	Type	Required	Description
version	integer	false	The representation version (1).
types	object	false	The type configuration keyed by type name. Type names can contain up to 36 alphanumeric characters and underscores but cannot start with an underscore.
links	array [object]	false	Zero or more links to related resources or operations. See the link relations table for a description of the link types.

Status	Meaning	Description
200	OK	The request succeeded.
400	Bad Request	The request is malformed or contains invalid parameter values.		Schema

Import configuration

Request Samples

Response Samples

Query Parameters

Request Body

Responses