Eyeglass Search GraphQL API
- Overview
- Summary
- Query Format and routes
- Endpoint:
- Parameter Encoding
- Authentication
- login
- Query
- Response
- Example:
- Queries
- fileInfo
- Query
- Response
- Example 1: Run an empty query to get all of the file names and owners
- Example 2: Paginate through *.txt files
- getSummaryReport
- Query
- Response
- Example 2: Groups all of the files on a path by last modified date
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:
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, 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
| ||
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.
curl -s -G -k -H Authorization:"Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJTSUQ6Uy0xLTUtMjEtMjAxODMyNTY2LTMxODczNTM0MDctMjgyOTk5MTcxMC0xNDQ4Iiwicm9sZSI6IlVTRVIiLCJleHAiOjE1NzAyODk3MTR9.0vs-tnOgs0cOBSYB_SOuNHdmV7NT6YisTwuIbZFMkJE" https://search.igls.com/graphql --data-urlencode 'query={ 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: - 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 } ] } } } |
© Superna Inc