Administration Guides

Eyeglass Search GraphQL API

Home




Overview

The API guide provides API usage guidelines for customers that 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.

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 is to 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:

Login with the username: testuser@exampledomain.com, using password: NotReal!:


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

  login(id:"testuser@exampledomain.com", pass:"NotReal!") {

    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,

  startCursor: Int,

  createNewQuery: String,

  filePath: String,

  clusterGuid: String,

  fileSizeMin: String,

  fileSizeMax: String,

  rowsPerQuery: Int,

  group: String,

  stub: String,

  historySearch: Boolean

): FileInfoList

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.

startCursor

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

type PageInfo {

 totalNum: Long!

 startCursor: Int!

 hasNextPage: Boolean!

 qTime: Int

}

Field

Type

Value

totalNum (non-null)

Long

Total number of records that were matched by this query

startCursor (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.

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 windows-specific network UNC of the file as computed by the user’s share access.  

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 atime 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 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 that’s stubbed to a cloudpool.

blockSize

String

The blocksize 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.

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

            startCursor

            hasNextPage

        }

        fileList {

            fileName

            ownerName

        }

  }

}'

{

        "data": {

            "fileInfo": {

                "fileList": [

                    {

                        "fileName": "First Installation.txt",

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

                    }

                ],

                "pageInfo": {

                    "hasNextPage": true,

                    "startCursor": 1,

                    "totalNum": 3

                }

            }

        }

}

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

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

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

        pageInfo {

            totalNum

            startCursor

            hasNextPage

        }

        fileList {

            fileName

            ownerName

        }

  }

}'

{

        "data": {

            "fileInfo": {

                "fileList": [

                    {

                        "fileName": "Post Installation.txt",

                        "ownerName": "root"

                    }

                ],

                "pageInfo": {

                    "hasNextPage": true,

                    "startCursor": 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,

  fileSizeMin: String,

  fileSizeMax: String,

  creationStart: String,

  creationEnd: String,

  lastAccessStart: String,

  lastAccessEnd: String,    

  lastModifiedStart: String,

  lastModifiedEnd: String,

  stub: String,

  facetSortField: String,

  facetSortOrder: FacetSortOrder,

  facetTimeGroupBy: FacetTimeGroupBy,

  facetLimit: Int,

  facetField: String!,

  clientTimeZone: 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”.

Response

Schema

type SummaryReportList {

  pageInfo: PageInfo

  summaryList: [SummaryReport]

}

Field

Type

Value

pageInfo

Object (PageInfo)

Information on the query and on rows.

summaryList

List of Objects (SummaryReport)

A list of SummaryReport objects.

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.

type SummaryReport {

  name: String

  count: Long

  total: Long

  average: Float

}

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

                }

            ]

        }

    }

}


© Superna LLC