Search

Search Documents

This is the endpoint used to search in the document store.

Search Documents

POST https://api.everisbigcontent.com/edms/rest/v1/search?accept={RETURN_TYPE}

Retrieves all the documents that match the query.

We use our own query structure, that allows us to search by metadata or by content.

While searching by metadata, we must define the field we are interested in. We must also specify the value and the operation to apply. We support the operations equals (eq), greater than (gt), greater than or equals (gte), lower than (lt), lower than or equals(lte), like (like), like ignoring case (like_nocase), in (in) and not in (nin). If we search by multiple fields, it makes the AND operation so it will return the documents that match all the fields of the query.

The search by content looks for the specified words in the file itself (word, pdf, txt…). It allows to specify if we want to search only in the current versions, or in all the versions by using (current) boolean. It makes the OR between the words, so it returns all the documents that have any of the specified words.

Currently the searches by metadata and content cannot be mixed. If we try to search by both, the metadata conditions will prevail and only metadata results will be retrieved.

If we don’t specify any query parameters, we will get all the documents in the document store.

Our query system also allows to define the structure of the result. We can specify how to order the result with the (orderBy) option, what fields of the document to show (fields) and how to divide the result in pages with (page).

The search by categories can be done in two ways:

Searching a metadata properties in all categories.
Searching a metadata properties in a specific category.

These two forms can be combined to make a more specific search.

More details in section Search by categories.

Currently the limit of the query output is 3000 documents.

Parameters

HTTP Headers

HTTP headers allow pass additional information with the request or the response. BigContent headers are used for recurrent details like authentication or document store.

Table 1. Headers
Name	Example	Description
`Document-Store`	`invoice_store`	Document Store identifier
`Authorization`	`Bearer ha9r6DG4e5AQ84gferAd8EQ…`	Mandatory header of String type that authorizes you as the user with the right to execute this operation. The string is a Bearer Token returned from the operation create token
`Access-User`	john@company.com or john or 211555 or …	Optional header that allows to send an additional user identifier associated with the operation. May be required depending on specific document store configuration. The value is a free style string to identify the individual user who has sent the request.
`Content-Type`	`application/json`	The Content-Type entity header is used to indicate the media type of the resource. In this case, it must be `application/json`

Query Parameters

Name Allowed values Detail

Name	Allowed values	Detail
`accept`	`array`, `object`	If `array`, the search returns a JSON array with the metadata of all the documents. If `object`, it adds the total number of documents that match the query. Note this is not the number of documents returned (as this can be set with the query parameter `page`), it is the number of existing documents that match the query

accept

array, object

If array, the search returns a JSON array with the metadata of all the documents. If object, it adds the total number of documents that match the query. Note this is not the number of documents returned (as this can be set with the query parameter page), it is the number of existing documents that match the query

Body

As indicated by headers, the body of the http request must be a JSON object.

Search by Metadata Example

{
  "metadata": [
    {
      "field": "description",
      "operand": "eq",
      "value": "This is the template for invoices"
    },
    {
      "field": "author",
      "operand": "eq",
      "value": "john@company.com"
    },
    {
      "field": "categories.attributeName",
      "operand": "eq",
      "value": "stringValue"
    },
    {
      "field": "categories.nameCategory",
      "operand": "eq",
      "value": {"attributeName" : "stringValue","attributeName2": integerValue}
    }
  ],
  "fields": [
    "description", "categories"
  ],
  "orderBy": {
    "asc": true,
    "fields": [
      "category._name",
      "dateCreated"
    ]
  },
  "page": {
    "number": 1,
    "size": 50
  }
}

Search by Content Example

{
  "content": {
    "current": true,
    "words": [
      "invoice", "template"
    ]
  },
  "fields": [
    "description", "categories"
  ],
  "orderBy": {
    "asc": true,
    "fields": [
      "category._name",
      "dateCreated"
    ]
  },
  "page": {
    "number": 1,
    "size": 50
  }
}

Table 2. Metadata
Field name	Allowed values	Detail
field	`String`	The field of the metadata to be searched
operand	`eq`, `gt`, `gte`, `lt`, `lte`, `like`, `like_nocase`, `in` and `nin`	Type of comparison that the search will apply. If not specified, `eq` is applied
value	The values supported are Strings, Integers and object.	The object must have the following structure {"PropertyString" : "String","PropertyNumber": 1} , the field must contains 'category.NameOfCategory' .

Value type String is not supported with range operands : gt,gte,lt,lte.

Table 3. Content
Field name	Allowed values	Detail
current	`true`, `false`	If true, the search will only happen in the current version of the content
words	List of `Strings`	The list of words to be searched in the content. An OR is applied, so it will return all the documents that contains ANY of the words in the list

Table 4. Fields
Allowed values	Detail
List of `Strings`	The fields to show in the result of the search. The JSONs of the documents will only have those fields in addition to documentId and _hidden (if user is admin). If no one is selected, it will show the whole metadata

Table 5. OrderBy
Field name	Allowed values	Detail
asc	Boolean (`true`, `false`)	`true` by default. If set to `false` the result of the search will be ordered in descendent order
fields	List of `Strings`	The result will be ordered taking into account the values of those fields. If more than one is provided, it will order it by the first one. Then, all the documents with the same value for the first field will be ordered by the value of the second field. This process will continue until all the fields of the list have been taken into account

For dates we accept both timestamps and date formated strings.

The timestamp follows Unix time conventions, representing the time in milliseconds since January 1st, 1970 UTC. In case of using a string, it must adhere to the following format yyyy-MM-ddTHH:mm:ss.SSSZ. Where the T is used to separate date and time, and the Z is the zone designator for the zero UTC offset. If another offset is needed (e.g. London time), we must replace the Z by +01.

Table 6. Page
Field name	Allowed values	Detail
number	Any `Integer`	The number of the page to show, starting to count by 1. If we select number 2 and size 50, you will get the second batch of 50 documents
size	Any `Integer`	The number of documents in each page

Table 7. Operand
Operand	Allowed values	Detail
`eq`	Any Integer or String	The value needs to be exactly the same as the searched
`gt`	Any Integer	The value needs to be greater than the searched
`gte`	Any Integer	The value needs to be greater than or equal to the searched
`lt`	Any Integer	The value needs to be lower than the searched
`lte`	Any Integer	The value needs to be lower than or equal to the searched
`like`	Any String	The string needs to contain the substring searched
`like_nocase`	Any String	The string needs to contain the substring searched ignoring lower or upper case
`in`	Any String	The value of a field equals any value in the specified array
`nin`	Any String	The field value can not be one of the options present in the string separated by commas

Responses

Success

Successful responses can be easily identified being always 20x (e.g. 200, 201).

Table 8. Success response
Field	Example	Description
Status code	`200`	`OK`
`Content-Type`	`application/json`	The Content-Type entity header is used to indicate the media type of the resource. In this case, it must be `application/json`
Body	JSON response accept array JSON response accept object	A JSON containing the set of documents matching the query conditions. Also if we have sent the query parameter `accept=object` in the request, the total number of documents that match the query will be retrieved.

JSON object (accept=array)

[
    {
      "id" : "qga8r5hsy9rw5weggf93lopa58",
      "description" : "Invoice template",
      "_hidden" : false,
      "author" : "john@company.com",
      "dateCreated" : "2018-10-24T07:10:51.709Z",
      "lastModifier" : "john@company.com",
      "dateModified" : "2018-10-24T07:10:51.709Z",
      "currentVersion" : "1.0",
      "content" : [
       {
         "id" : "g8q9ppihd58art2f9op1sq28gh",
         "name" : "invoice.pdf",
         "type" : "application/pdf",
         "size" : 58943,
         "majorVersion" : 1,
         "minorVersion" : 0,
         "_hidden" : false,
         "author" : "john@company.com",
         "dateCreated" : "2018-10-24T07:10:51.709Z",
         "lastModifier" : "john@company.com",
         "dateModified" : "2018-10-26T09:15:55.980Z"
       }
      ],
      "categories" : [
       {
         "_name": "template",
         "Type": "invoice",
         "date": "2018-10-24T07:10:51.709Z",
         "boolean": true
       }
      ],
      "documentStore" : "invoice_store"
    },
    {
      "id" : "zopprkbhpfctvmwq5y75quhlum",
      "description" : "Receipt template",
      "_hidden" : false,
      "author" : "john@company.com",
      "dateCreated" : "2018-10-26T09:15:55.980Z",
      "lastModifier" : "john@company.com",
      "dateModified" : "2018-10-26T09:15:55.980Z",
      "currentVersion" : "1.0",
      "content" : [
       {
         "id" : "66oelseazjg3deimgjiarhiskq",
         "name" : "receipt.pdf",
         "type" : "application/pdf",
         "size" : 6543,
         "majorVersion" : 1,
         "minorVersion" : 0,
         "_hidden" : false,
         "author" : "john@company.com",
         "dateCreated" : "2018-10-26T09:15:55.980Z",
         "lastModifier" : "john@company.com",
         "dateModified" : "2018-10-26T09:15:55.980Z"
       }
      ],
      "categories" : [
       {
         "_name": "calendar",
         "Month": "february",
         "Year": "1998"
       }
      ],
      "documentStore" : "invoice_store"
    }
]

JSON object (accept=object)

{
  "results": [
    {
      "id" : "qga8r5hsy9rw5weggf93lopa58",
      "description" : "Invoice template",
      "_hidden" : false,
      "author" : "john@company.com",
      "dateCreated" : "2018-10-24T07:10:51.709Z",
      "lastModifier" : "john@company.com",
      "dateModified" : "2018-10-24T07:10:51.709Z",
      "currentVersion" : "1.0",
      "content" : [
       {
         "id" : "g8q9ppihd58art2f9op1sq28gh",
         "name" : "invoice.pdf",
         "type" : "application/pdf",
         "size" : 58943,
         "majorVersion" : 1,
         "minorVersion" : 0,
         "_hidden" : false,
         "author" : "john@company.com",
         "dateCreated" : "2018-10-24T07:10:51.709Z",
         "lastModifier" : "john@company.com",
         "dateModified" : "2018-10-26T09:15:55.980Z"
       }
      ],
      "categories" : [
       {
         "_name": "template",
         "Type": "invoice",
         "date": "2018-10-24T07:10:51.709Z",
         "boolean": true
       }
      ],
      "documentStore" : "invoice_store"
    },
    {
      "id" : "zopprkbhpfctvmwq5y75quhlum",
      "description" : "Receipt template",
      "_hidden" : false,
      "author" : "john@company.com",
      "dateCreated" : "2018-10-26T09:15:55.980Z",
      "lastModifier" : "john@company.com",
      "dateModified" : "2018-10-26T09:15:55.980Z",
      "currentVersion" : "1.0",
      "content" : [
       {
         "id" : "66oelseazjg3deimgjiarhiskq",
         "name" : "receipt.pdf",
         "type" : "application/pdf",
         "size" : 6543,
         "majorVersion" : 1,
         "minorVersion" : 0,
         "_hidden" : false,
         "author" : "john@company.com",
         "dateCreated" : "2018-10-26T09:15:55.980Z",
         "lastModifier" : "john@company.com",
         "dateModified" : "2018-10-26T09:15:55.980Z"
       }
      ],
      "categories" : [
       {
         "_name": "calendar",
         "Month": "february",
         "Year": "1998"
       }
      ],
      "documentStore" : "invoice_store"
    }
  ],
  "totalSize": 2
}

See document metadata for more details about the document properties.

Error

In case of error, the response body contains a JSON object with additional information:

span-id: auto-generated identifier of the request. Please provide this when asking for support in our forum.
message: descriptive message of the error. This is aimed for developers and is specially important for Bad Request errors., where contains hints on how to fix the request.

Error messages should not be used to validate errors since they may be subject to change.

Example

{
  "span-id" : "7eb38962-2618-85f9-brte-4f15f6729590",
  "message" : "No match found for the Id"
}

Table 9. Error messages
Status code	Message	Description
400	`Malformed JSON exception (line _, col _): …`	The JSON body has a bad structure. Message points where is the problem with line and column numbers as well as what is the problem (e.g. double "{", or a missing ",", …)
400	`Malformed JSON exception (line _, col _): Can not deserialize value of type…`	In the position X, Y there is a field that can accept only a set of values. The value you are using isn’t in that set
400	`Malformed JSON exception (line _, col _): Invalid UTF-8 middle byte…`	The encoding used to send the object was not `UTF-8`. This error can happen due to launching a curl in git-bash
401	`The Token has expired on…`	Has passed more than an hour since the last create token or refresh token operation
400	`Conditions cannot have fields with null value`	The field or the value of a search condition sent in the body is null
401	`Malformed token`	The token sent is not valid
401	`Problems parsing token`	An empty token has been sent
401	`The Document-Store header must be set`	The header indicating the document store that you want to access, must be set
403	`User _ has no rights to access to the DocumentStore _`	We dont have access to that document store, or it is misspelled
415	`Content type _ not supported`	The Content-Type header is not correctly set
500	`Internal server error`	If it happens consistently, please report it on our forum

Code examples

cURL
Java
Node.js

curl "https://api.everisbigcontent.com/edms/rest/v1/search?accept=object" \
-X POST \
-H "Authorization: Bearer ha9r6DG4e5AQ84gferAd8EQ..." \
-H "Document-Store: invoice_store" \
-H 'Content-Type: application/json' \
-d "{\"metadata\": [ { \"field\": \"id\", \"value\":\"qga8r5hsy9rw5weggf93lopa58\", \"operand\": \"eq\"} ]}"

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

String url = "https://api.everisbigcontent.com/edms/rest/v1/search/";
String token = "Bearer ha9r6DG4e5AQ84gferAd8EQ...";
String documentStore = "invoice_store";
String query = "{\"metadata\": [ { \"field\": \"id\", \"value\":\"qga8r5hsy9rw5weggf93lopa58\", \"operand\": \"eq\"} ]}"

final CloseableHttpClient client = HttpClients.createDefault();
final HttpPost post = new HttpPost(url);
post.setHeader("Authorization", token);
post.setHeader("Document-Store", documentStore);
post.setHeader("Content-type", "application/json");
StringEntity entity = new StringEntity(query);
entity.setContentEncoding(String.valueOf(StandardCharsets.UTF_8));
entity.setContentType("application/json");
post.setEntity(entity);
CloseableHttpResponse response = client.execute(post);
String responseString = EntityUtils.toString(response.getEntity(), StandardCharsets.UTF_8);

var request = require('request');
var token = 'Bearer ha9r6DG4e5AQ84gferAd8EQ...';
var documentStore = 'invoice_store'

request.post({
  headers: {
    'Authorization': token,
    'Content-Type': 'application/json',
    'Document-Store': documentStore
  },
  url: "https://api.everisbigcontent.com/edms/rest/v1/search/",
  json: {
    "metadata": [
      {
        "field": "id",
        "operand": "eq",
        "value":"qga8r5hsy9rw5weggf93lopa58"
      }
    ]
  }
}, function (error, response, body) {
  console.log(body);
});

Search by categories

Currently the following ways to search documents by categories are the following:

Searching a metadata properties in all categories.
Searching a metadata properties in a specific category.
Combined search.

Searching a metadata properties in all categories

This query return the documents with a specific attribute in any of their metadata properties.

The example search the documents that contains the following condition:

Document that contains any category with attribute named "code" with value between 2 and 5.

{
  "metadata": [
    {
      "field": "category.code",
      "operand": "gte",
      "value": 2
    },
    {
      "field": "category.code",
      "operand": "lte",
      "value": 5
    }
  ]
}

Searching a metadata properties in a specific category

This query returns the documents with specific metadata properties in a specific category.

The example search the documents that contains the following conditions:

Category named "policy" contains an attribute named "code" with values between 2 and 5.
Category named "policy" contains an attribute named "policy_number" with values between 5 and 10.

{
  "metadata": [
    {
      "field": "category.policy",
      "operand": "gt",
      "value": {"code" : 2,"policy_number": 5}
    },
    {
      "field": "category.policy",
      "operand": "lt",
      "value": {"code" : 5,"policy_number": 10}
    }
  ]
}

Combined search

This is a combination of the previous examples.

This query returns the documents with a specific attribute in any of their metadata properties and specific metadata properties in a concrete category

The example search the documents that contains the following conditions:

Category named "policy" contains an attribute named "code" with values between 2 and 5.
Category named "policy" contains an attribute named "policy_number" with values between 5 and 10.
Contains any category with attribute named "priority" with value "low".

{
  "metadata": [
    {
      "field": "category.policy",
      "operand": "gt",
      "value": {"code" : 2,"policy_number": 5}
    },
    {
      "field": "category.policy",
      "operand": "lt",
      "value": {"code" : 5,"policy_number": 10}
    },
    {
      "field": "category.priority",
      "operand": "eq",
      "value": "low"
    }
  ]
}

Query examples

In this section there are some examples about how to use the system queries used in the platform.

By document Id

{
  "metadata": [
    {
      "field": "id",
      "operand": "eq",
      "value": "qga8r5hsy9rw5weggf93lopa58"
    }
  ]
}

This query returns a document with the Id qga8r5hsy9rw5weggf93lopa58

By content Id

{
  "metadata": [
    {
      "field": "content.id",
      "operand": "eq",
      "value": "g8q9ppihd58art2f9op1sq28gh"
    }
  ]
}

This query returns a document that contains in one of its contents the Id g8q9ppihd58art2f9op1sq28gh

By exact description

{
  "metadata": [
    {
      "field": "description",
      "operand": "eq",
      "value": "Invoice template"
    }
  ]
}

This query returns the documents with the description Invoice template

By array of exact description

{
  "metadata": [
    {
      "field": "description",
      "operand": "in",
      "value": [
        "Invoice template",
        "Other Search"
      ]
    }
  ]
}

This query returns the documents with the description is equals Invoice template or Other Search

By comma separed values of exact description

{
  "metadata": [
    {
      "field": "description",
      "operand": "in",
      "value": "Invoice template, Other Search"
    }
  ]
}

This query returns the documents with the description is equals Invoice template or Other Search

By description containing Strings

{
  "metadata": [
    {
      "field": "description",
      "operand": "like_nocase",
      "value": "invoice"
    },
    {
      "field": "description",
      "operand": "like_nocase",
      "value": "template"
    }
  ]
}

This query returns the documents with the words invoice and template in the description. like_nocase will ignore if it is in lower or upper case. If you don' want to ignore it, use like instead.

By dateCreated after Date

{
  "metadata": [
    {
      "field": "dateCreated",
      "value":"2018-11-09T11:35:00.000Z",
      "operand": "gt"
    }
  ]
}

This query returns the documents created after 2018-11-09T11:35:00.000Z

By dateCreated before Date

{
  "metadata": [
    {
      "field": "dateCreated",
      "value":"2018-11-09T11:35:00.000Z",
      "operand": "lt"
    }
  ]
}

This query returns the documents created before 2018-11-09T11:35:00.000Z

By dateCreated between Dates

{
  "metadata": [
    {
      "field": "dateCreated",
      "value":"2018-11-09T11:30:00.000Z",
      "operand": "gt"
    },
    {
      "field": "dateCreated",
      "value":"2018-11-09T11:35:00.000Z",
      "operand": "lt"
    }
  ]
}

This query returns the documents created between 2018-11-09T11:30:00.000Z and 2018-11-09T11:35:00.000Z

By content and description, obtaining only id and description

{
  "content": {
    "current": true,
    "words": [
      "invoice", "template"
    ]
  },
  "metadata": [
    {
      "field": "description",
      "operand": "eq",
      "value": "Invoice template"
    }
  ],
  "fields" : [
    "id", "description"
  ]
}

This query returns the documents whose decription is Invoice template and have the words invoice or template in the file. In the returned JSON only the values id and description will be retrieved.

By content and description using pagination

{
  "content": {
    "current": true,
    "words": [
      "invoice", "template"
    ]
  },
  "metadata": [
    {
      "field": "description",
      "operand": "eq",
      "value": "Invoice template"
    }
  ],
  "page": {
    "number": 2,
    "size": 10
  }
}

This query returns the second page with the next 10 documents whose description is Invoice template and have the words invoice or template in the file.

By category name, ordered by dateCreated

{
  "metadata": [
    {
      "field": "category._name",
      "value":"template",
      "operand": "eq"
    }
  ],
  "orderBy" : {
    "asc" : false,
    "fields" : [
      "dateCreated"
    ]
  }
}

This query returns the documents with the category template ordered by the creation date, showing most recent ones first.

By dateCreated between Dates, ordered by category and dateCreated

{
  "metadata": [
    {
      "field": "dateCreated",
      "value":"2018-10-09T11:30:00.000Z",
      "operand": "gt"
    },
    {
      "field": "dateCreated",
      "value":"2018-11-09T11:35:00.000Z",
      "operand": "lt"
    }
  ],
  "orderBy" : {
    "asc" : false,
    "fields" : [
      "category._name",
      "dateCreated"
    ]
  }
}

This query returns the documents created between 2018-10-09T11:30:00.000Z and 2018-11-09T11:35:00.000Z. It will retrieved them ordered alphabetically by its category name and document creation date.

By content

{
  "content": {
    "current": true,
    "words": [
      "invoice", "template"
    ]
  }
}

This query returns the documents that contains the words invoice or template in the file of the current version.

By content and description

{
  "content": {
    "current": true,
    "words": [
      "invoice", "template"
    ]
  },
  "metadata": [
    {
      "field": "description",
      "operand": "eq",
      "value": "Invoice template"
    }
  ]
}

This query returns the documents whose decription is Invoice template and have words invoice or template in the file.

By content name and between dates

{
  "metadata": [
    {
      "field": "content.name",
      "operand": "in",
      "value": [
      "invoice",
      "template"
      ]
    },
    {
      "field": "dateCreated",
      "value":"2018-11-09T11:30:00.000Z",
      "operand": "gt"
    },
    {
      "field": "dateCreated",
      "value":"2018-12-09T11:35:00.000Z",
      "operand": "lt"
    }
  ]
}

This query returns the documents whose name is invoice or template and were created between 2018-11-09T11:30:00.000Z and 2018-12-09T11:35:00.000Z.

By category property value

{
  "metadata": [
    {
      "field": "category.Type",
      "value":"Invoice",
      "operand": "eq"
    }
  ]
}

This query returns the documents with the property "Type" equals to "Invoice" in any of the document’s Categories.

By category properties value, searching number value in range

{
  "metadata": [
    {
      "field": "category.number",
      "value":1,
      "operand": "gt"
    },
    {
      "field": "category.number",
      "value":5,
      "operand": "lt"
    }
  ]
}

This query returns the documents that contain in any of their categories the property number with value between 1 and 5 (values 1 and 5 not included).

By category properties value, searching by number in range with inclusive operands

{
  "metadata": [
    {
      "field": "category.code",
      "operand": "gte",
      "value": 2
    },
    {
      "field": "category.code",
      "operand": "lte",
      "value": 5
    }
  ]
}

This query returns the documents that any of its categories contains the property named code with values between 2 and 5 (values 2 and 5 included).

By category name with multiple properties values

{
  "metadata": [
    {
      "field": "category.document",
      "operand": "eq",
      "value": {"type" : "car","policy_number": 2}
    }
  ]
}

This query returns the documents whose category named document and whose field named type with value car and field named policy_number with value 2.

By category name with multiple property values, searching numbers within a range

{
  "metadata": [
    {
      "field": "category.document",
      "operand": "gt",
      "value": {"code" : 2,"policy_number": 5}
    },
    {
      "field": "category.document",
      "operand": "lt",
      "value": {"code" : 5,"policy_number": 10}
    }
  ]
}

This query returns the documents with category named document whose attribute named code with values between 2 and 5 and field named policy_number with values between 5 and 10.

By category properties values specifying category name combined with a metadata property of any category

{
  "metadata": [
    {
      "field": "category.document",
      "operand": "gte",
      "value": {"code" : 2,"policy_number": 5}
    },
    {
      "field": "category.document",
      "operand": "lte",
      "value": {"code" : 5,"policy_number": 10}
    },
    ,
    {
      "field": "category.number",
      "value":12,
      "operand": "gt"
    }
  ]
}

This query returns the documents whose contains a category named document with a field named code with values between 2 and 5 and field named policy_number with values between 5 and 10 and in any category that contains an attribute named number with value greater than 12.

By category property value, ordered by dateCreated

{
  "metadata": [
    {
      "field": "category._name",
      "value":"template",
      "operand": "eq"
    },
    {
      "field": "category.Type",
      "value":"Invoice",
      "operand": "eq"
    }
  ],
  "orderBy" : {
    "asc" : false,
    "fields" : [
      "dateCreated"
    ]
  }
}