Administration Guides

Eyeglass Search GraphQL API

Home

Overview

The API guide provides API usage guidelines for customers who want to automate searches and use the file results in an automation process. The API could also be used to integrate the search results in indexing into custom-developed applications or web pages. The scope of this integration is outside the scope of the API documentation.

Documentation based on version: 1.2.0-23173

Summary

The Eyeglass Search GraphQL API (ESGA) is an authenticated, remote interface that runs over http for querying an Eyeglass search appliance for files.

Query Format and routes

Queries to ESGA can be issued to any node in the search cluster. Queries run over https with the bulk of the query passed as URL parameters.

Endpoint:

All Queries must be issued to: https://ip.of.search.node/graphql

Parameter Encoding

GraphQL queries must be issued as a URL encoded value to the query http parameter:

https://ip.of.search.node/graphql?query=url_encoded_graphql_query

Examples of using curl to encode the query can be seen below.

Authentication

Authentication is achieved through the retrieval of a JSON web token. This token will be included in the “Bearer” header of all future calls to ESGA.

login

Query

Schema
login(id: String!, pass: String!): LoginResult
Argument	Type	Value
id (required)	String	Username + domain of the user logging in, in the user@domain.com syntax. For local users, omit the domain.
pass (required)	String	Password of the user attempting to log in.

Response

Schema
type: LoginResult { user: User! token: String! }
Field	Type	Value
user (non-null)	Object (User)	User Object Object for the logged-in user.
token (non-null)	String	The JSON Web Token to be used in authorizing future ESGA calls.
type: User { name: String! role: String! }
Field	Type	Value
name (non-null)	String	The name of the logged in user, in DOMAIN\username format
role (non-null)	String	one of: USER or ADMIN

Example:

curl -s -G -k https://search.igls.com/graphql --data-urlencode 'query={

user {

name

role

}

token

}

{

"data": {

"login": {

"token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJTSUQ6Uy0xLTUtMjEtMjAxODMyNTY2LTMxODczNTM0MDctMjgyOTk5MTcxMC0xNDQ4Iiwicm9sZSI6IlVTRVIiLCJleHAiOjE1NzAyODk3MTR9.0vs-tnOgs0cOBSYB_SOuNHdmV7NT6YisTwuIbZFMkJE",

"user": {

"name": "EXAMPLEDOMAIN\\testuser",

"role": "USER"

}

For any authenticated endpoints, the value of token needs to be used in the Authorization header using the Bearer schema

Authorization: Bearer <token>

Queries

fileInfo

The main query to execute searches. Returns a list of file records that match the provided query.

Query

Schema
fileInfo( content: String, fileName: String, fileExt: String, lastModifiedStart: String, lastModifiedEnd: String, fileOwner: String, lastAccessStart: String, lastAccessEnd: String, creationStart: String, creationEnd: String, fetchedRecords: Int, createNewQuery: String, filePath: String, clusterGuid: String, fileSizeMin: String, fileSizeMax: String, rowsPerQuery: Int, group: String, stub: String, historySearch: Boolean classification: String, operatorsClassification: String, isilons: String, metadata: [MetadataMap] ): FileInfoList `input MetadataMap { key: String value: String }`
Argument	Type	Value
content	String	Search for words in files. Accepts simple words and phrases, or more complicated Lucene queries, of the form “dog AND ( cat OR bat )”
fileName	String	Search for files with this exact filename, not including the path, but including the extension. Accepts wildcards.
fileExt	String	Search for files with this file extension. The extension is defined as the set of characters after the last dot (.) in the filename.
lastModifiedStart	String	filter by documents that have a last modified timestamp later in time than the value that is set here. Dates must be formatted with the `YYYY-MM-DDThh:mm:ssZ` format. For example, 03:14 in the morning of March 14, 2020 is written 2020-03-14T03:14:15Z
lastModifiedEnd	String	filter by documents that have a last modified timestamp earlier in time than the value that is set here. See lastModifiedStart for syntax and example.
lastAccessStart	String	filter by documents that have a last accessed timestamp later in time than the value that is set here. atimes must be enabled on your PowerScale cluster. See lastModifiedStart for syntax and example.
lastAccessEnd	String	filter by documents that have a last accessed timestamp earlier in time than the value that is set here. atimes must be enabled on your PowerScale cluster. See lastModifiedStart for syntax and example.
creationStart	String	filter by documents that have a created timestamp later in time than the value that is set here. See lastModifiedStart for syntax and example.
creationEnd	String	filter by documents that have a created accessed timestamp earlier in time than the value that is set here. See lastModifiedStart for syntax and example.
fileOwner	String	return only documents that match this file owner. Owners must be specified in the DOMAIN\user format.
filePath	String	Search for files that begin with the specified path, starting with /ifs
clusterGuid	String	Search for files that exist on the cluster specified by this GUID.
fileSizeMin	String	In bytes, the minimum file size to return in the search results.
fileSizeMax	String	In bytes, the maximum file size to return in the search results.
group	String	Filter the search results to those that are owned by this particular group. Groups must be in DOMAIN\group syntax.
stub	String	True or False, limit the results to files that are SmartLinked files (for true), or files that are not SmartLinked files (for false).
historySearch	Boolean	Execute the search in the history collection instead of the main. Reports on previous versions of documents in snapshots.
fetchedRecords	Int	Cursor to use to start the search. Provide this value in conjunction with rowsPerQuery to paginate the search results.
rowsPerQuery	Int	Maximum number of records to return. If the number of available results exceeds rowsPerQuery, use the cursor value to paginate future responses.

Response

Schema
type FileInfoList { pageInfo: PageInfo fileList: [FileInfo] }
Field	Type	Value
pageInfo	Object (PageInfo)	Information on the query and on rows.
fileLIst	List of Objects (FileInfo)	A list of FileInfo objects

SubSchema
type PageInfo { totalNum: Long! fetchedRecords: Int! hasNextPage: Boolean! qTime: Int }
Field	Type	Value
totalNum (non-null)	Long	Total number of records that were matched by this query
fetchedRecords (non-null)	Int	A cursor to use to resume this query
hasNextPage (non-null)	Boolean	True if this is not the final page of results
qTime	Int	The time (in milliseconds) that the query took to return.

SubSchema
type FileInfo { fileName: String clusterName: String path: String displayPath: String ownerSid: String ownerName: String creationTime: String lastWriteTime: String lastAccessTime: String fileSize: String extension: String type: String contentIndexedAt: String metadataIndexedAt: String group: String stub: String changedTime: String blockSize: String mode: String language_s: String snapShotName: String isHidden: String }
fileName	String	The filename (without path) of this file.
clusterName	String	The name of the PowerScale cluster where this file resides
path	String	The absolute path to the file on the PowerScale cluster
displayPath	String	The user’s share access computes the Windows-specific network UNC of the file.
ownerName	String	The name of the user that owns this file
creationTime	String	Epoch seconds timestamp of when this file was created.
changedTime	String	Epoch seconds timestamp of the last time this file was modified
lastAccessTime	String	Epoch seconds timestamp of the last time this file was accessed. Requires time tracking on the PowerScale to be enabled.
fileSize	String	In bytes, the size of this file
extension	String	The file extension. The extension is defined as the set of characters after the last dot (.) in the filename.
type	String	either CONTAINER for the directory or OBJECT for a file.
contentIndexedAt	String	Epoch seconds of the server time when the content of this file was last indexed.
metadataIndexedAt	String	Epoch seconds timestamp of the server time when the metadata of this file was last indexed.
group	String	the group that owns the file.
stub	String	True if the object is a smartlink file stubbed to a cloudpool.
blockSize	String	The block size of the file
mode	String	The octal mode of the file, according to standard posix file permissions.
language_s	String	The detected language of the file’s content.
isHidden	String	True if this represents a hidden file.
cToken	String	security token used by S3 cloud browser
filePool	List of String	list of files that exist in the file pool at the search moment
classification	String	classification rule that is applied during indexation operatorClassification
operatorsClassification	String
isilons	String	if more than one isilon cluster is added to the system, specify the list of isilons to search on
metadata (MetadataMap)	List of Objects(Metadata)	when the indexation target is S3 instead of Isilon, it contains a list of key-value pairs representing the file metadata

Example 1: Run an empty query to get all of the file names and owners

curl -s -G -k -H Authorization:"Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJTSUQ6Uy0xLTUtMjEtMjAxODMyNTY2LTMxODczNTM0MDctMjgyOTk5MTcxMC0xNDQ4Iiwicm9sZSI6IlVTRVIiLCJleHAiOjE1NzAyODk3MTR9.0vs-tnOgs0cOBSYB_SOuNHdmV7NT6YisTwuIbZFMkJE" https://search.igls.com/graphql --data-urlencode 'query={

fileInfo {

pageInfo {

totalNum

}

fileList {

fileName

ownerName

}

{

"data": {

"fileInfo": {

"fileList": [

{

"fileName": "kf-demo-u1",

"ownerName": "root"

{

"fileName": "First Installation.txt",

"ownerName": "AD02\\kf-demo-u1"

{

"fileName": "Post Installation.txt",

"ownerName": "root"

{

"fileName": "Post Touch.txt",

"ownerName": "root"

}

"pageInfo": {

"totalNum": 4

}

Example 2: Paginate through *.txt files

Below are two curl requests for search results, the second one using the page info returned by the first call. In this example we’re limiting the number of results returned on each page to 1 for clarity.

ccurl -s -G -k -H Authorization:"Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJTSUQ6Uy0xLTUtMjEtMjAxODMyNTY2LTMxODczNTM0MDctMjgyOTk5MTcxMC0xNDQ4Iiwicm9sZSI6IlVTRVIiLCJleHAiOjE1NzAyODk3MTR9.0vs-tnOgs0cOBSYB_SOuNHdmV7NT6YisTwuIbZFMkJE" https://search.igls.com/graphql --data-urlencode 'query={

fileInfo(rowsPerQuery:1, fileExt:"txt") {

pageInfo {

totalNum

fetchedRecords

hasNextPage

}

fileList {

fileName

ownerName

}

{

"data": {

"fileInfo": {

"fileList": [

{

"fileName": "First Installation.txt",

"ownerName": "AD02\\kf-demo-u1"

}

"pageInfo": {

"hasNextPage": true,

"fetchedRecords": 1,

"totalNum": 3

}

The call to get the second page of results uses fetchedRecords:1 since that was returned by the first page.

fileInfo(fetchedRecords:1, rowsPerQuery:1, fileExt:"txt") {

pageInfo {

totalNum

fetchedRecords

hasNextPage

}

fileList {

fileName

ownerName

}

{

"data": {

"fileInfo": {

"fileList": [

{

"fileName": "Post Installation.txt",

"ownerName": "root"

}

"pageInfo": {

"hasNextPage": true,

"fetchedRecords": 2,

"totalNum": 3

}

getSummaryReport

The main query to execute roll up searches. This uses Solr’s faceting engine to group and summarize fields. (See https://lucene.apache.org/solr/guide/8_2/faceting.html for how faceting works.) This endpoint provides a simple abstraction on a few of the fields to roll up the queries and return summaries of the results. Filters that are applied in the fileInfo queries are also applicable here.

Query

Schema
getSummaryReport( content: String, fileExt: String, filePath: String, fileName: String, fileOwner: String, fileSizeMin: String, fileSizeMax: String, creationStart: String, creationEnd: String, lastAccessStart: String, lastAccessEnd: String, lastModifiedStart: String, lastModifiedEnd: String, stub: String, filePool: [String], facetSortField: String, facetSortOrder: FacetSortOrder, facetTimeGroupBy: FacetTimeGroupBy, facetLimit: Int, facetField: String!, reportType: String, createNewQuery: String, clientTimeZone: String, classification: String, operatorsClassification: String, isilons: String ): SummaryReportList
Argument	Type	Value
content	String	Search for words in files. Accepts simple words and phrases, or more complicated Lucene queries, of the form “dog AND ( cat OR bat )”
fileName	String	Search for files with this exact filename, not including the path, but including the extension. Accepts wildcards.
fileExt	String	Search for files with this file extension. The extension is defined as the set of characters after the last dot (.) in the filename.
lastModifiedStart	String	filter by documents that have a last modified timestamp later in time than the value that is set here. Dates must be formatted with the `YYYY-MM-DDThh:mm:ssZ` format. For example, 03:14 in the morning of March 14, 2020 is written 2020-03-14T03:14:15Z
lastModifiedEnd	String	filter by documents that have a last modified timestamp earlier in time than the value that is set here. See lastModifiedStart argument above for syntax and example.
lastAccessStart	String	filter by documents that have a last accessed timestamp later in time than the value that is set here. atimes must be enabled on your PowerScale cluster. See lastModifiedStart argument above argument above for syntax and example.
lastAccessEnd	String	filter by documents that have a last accessed timestamp earlier in time than the value that is set here. atimes must be enabled on your PowerScale cluster. See lastModifiedStart argument above for syntax and example.
creationStart	String	filter by documents that have a created timestamp later in time than the value that is set here. See lastModifiedStart argument above for syntax and example.
creationEnd	String	filter by documents that have a created accessed timestamp earlier in time than the value that is set here. See lastModifiedStart for syntax and example.
filePath	String	Search for files that begin with the specified path, starting with /ifs
fileSizeMin	String	In bytes, the minimum file size to return in the search results.
fileSizeMax	String	In bytes, the maximum file size to return in the search results.
stub	String	True or False, limit the results to files that are SmartLinked files (for true), or files that are not SmartLinked files (for false).
facetSortField	String	The result field to sort on. Can be one of: - total - count - average
facetSortOrder	Object(enum)	enum FacetSortOrder { ASC DESC } Sort results ascending (ASC) or descending (DESC)
facetTimeGroupBy	Object(enum)	enum FacetTimeGroupBy { DAY WEEK MONTH } For time range based facet queries, group the results by day, week, or month.
facetLimit	Int	The number of groups to return.
facetField	String (required)	The field to use for faceting. Supported fields are: - owner - group - extension - createdtime - lastmodified - filename - clustername - stub
clientTimeZone	String	The offset in hours of the current time zone. For Eastern Standard time, enter “-4”.
filePool	List of String	list of files that exist in the file pool at the search moment
reportType	String
classification	String	classification rule that is applied during indexation operatorClassification
operatorsClassification	String
isilons	String	if more than one isilon cluster is added to the system, specify the list of isilons to search on

Response

Schema
type SummaryReportList { pageInfo: PageInfo summaryList: [SummaryReport] predictedSummaryList: [SummaryReport] }
Field	Type	Value
pageInfo	Object (PageInfo)	Information on the query and on rows.
summaryList	List of Objects (SummaryReport)	A list of SummaryReport objects.
predictedSummaryList	List of Objects (SummaryReport)	based on the data that already exists for previous intervals of times, some predictions related to disk usage, file count, etc can be performed

SubSchema
type PageInfo { totalNum: Long! qTime: Int }
Field	Type	Value
totalNum (non-null)	Long	Total number of records that were matched by this query
qTime	Int	The time (in milliseconds) that the query took to return.

SubSchema
type SummaryReport { name: String count: Long total: Long average: Float }
Field	Type	Value
name	String	The name of this unique record. Value depends on the value that was chosen for faceting.
count	Long	The number of file records matching this name.
total	String	The summed value (in bytes) of all file records in this bucket.
average	String	The average filesize of all file records in this bucket.

Example 1: Get the counts and sizes of top two file extensions

Gets all of the extensions on the system, groups by extension, and sums the total bytes. Reports the data by default in descending count order.

curl -k -L -s -G -H Authorization:"Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJTSUQ6Uy0xLTUtMjEtMTk0MzI5MTcwNi0yNjMzMTY1NTY0LTIyOTIzNDIyNS0xMzE4Iiwicm9sZSI6IkFETUlOIiwiZXhwIjoxNTcwNjQ3NjQ5fQ.jzusrMyQdwv2vRLY2_8_ER2UunjwRYXoRwOAPpDAHrg" https://172.25.1.101/graphql --data-urlencode 'query={

getSummaryReport(facetField:"extension") {

pageInfo {

totalNum

}

summaryList {

name

count

total

average

}

{

"data": {

"getSummaryReport": {

"pageInfo": {

"totalNum": 2

"summaryList": [

{

"average": 229351.0,

"count": 34170,

"name": "ZIP",

"total": 7836955408

{

"average": 380176.0,

"count": 32483,

"name": "txt",

"total": 12349288443

}

]

}

Example 2: Groups all of the files on a path by last modified date

Accept a given path as a filter query. Group all of the files by last modified date, with monthly bucket results. Limit the results to a year’s worth of data by adding start and end modified dates to the query.

curl -GkLs -H Authorization:"Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJTSUQ6Uy0xLTUtMjEtMTk0MzI5MTcwNi0yNjMzMTY1NTY0LTIyOTIzNDIyNS0xMzE4Iiwicm9sZSI6IkFETUlOIiwiZXhwIjoxNTcwNjQ3NjQ5fQ.jzusrMyQdwv2vRLY2_8_ER2UunjwRYXoRwOAPpDAHrg" https://172.25.1.101/graphql --data-urlencode 'query={

getSummaryReport(

facetField:"lastmodified"

facetTimeGroupBy: MONTH

lastModifiedStart: "1539027461000"

lastModifiedEnd: "1570563482000"

filePath: "/ifs/data"

) {

pageInfo {

totalNum

}

summaryList {

name

count

total

average

}

{

"data": {

"getSummaryReport": {

"pageInfo": {

"totalNum": 10

"summaryList": [

{

"average": 127.0,

"count": 30444,

"name": "Fri Feb 01 00:00:00 UTC 2019",

"total": 3878443

{

"average": 0.0,

"count": 0,

"name": "Fri Mar 01 00:00:00 UTC 2019",

"total": 0

{

"average": 0.0,

"count": 0,

"name": "Mon Apr 01 00:00:00 UTC 2019",

"total": 0

{

"average": 0.0,

"count": 0,

"name": "Wed May 01 00:00:00 UTC 2019",

"total": 0

{

"average": 0.0,

"count": 0,

"name": "Sat Jun 01 00:00:00 UTC 2019",

"total": 0

{

"average": 0.0,

"count": 0,

"name": "Mon Jul 01 00:00:00 UTC 2019",

"total": 0

{

"average": 0.0,

"count": 0,

"name": "Thu Aug 01 00:00:00 UTC 2019",

"total": 0

{

"average": 0.0,

"count": 0,

"name": "Sun Sep 01 00:00:00 UTC 2019",

"total": 0

{

"average": 0.0,

"count": 0,

"name": "Tue Oct 01 00:00:00 UTC 2019",

"total": 0

{

"average": 0.0,

"count": 0,

"name": "Fri Nov 01 00:00:00 UTC 2019",

"total": 0

}

]

}