Searching Documents

About Document Versions & States:

  • Major Version Number: In Vault, these are 1.0, 2.0, 3.0, etc. These are also referred to as "Steady State" versions.
  • Minor Versions Number: In Vault, these are 0.1, 0.2, 1.1, 1.2, etc. These typically have the status "Draft" or "In Progress".
  • API Major & Minor Version Numbers: Version numbers are displayed differently in the API as shown in the first example response below.
  • Steady State: Vault documents that are in production and available for use. This state typically has the status "Approved" or "Effective".
  • Superseded State: Vault documents that have been archived or replaced by a new version. This state typically has the status "Superseded" or "Archived".
  • Obsolete State: Vault documents that have reached the end of their lifecycle or have retired document numbers. This state typically has the status "Obsolete" or "Retired".

All examples shown in this article query the document with keywords listed in the table below.

Article Contents

Searching Document Versions

Searching Document States

Searching Archived Documents

Searching Document Versions

The information in this section describes how Vault executes "basic" keyword searches (SELECT id FROM documents FIND 'string') on documents and how to expand the search scope by using the ALLVERSIONS and LATESTVERSION syntax.

As a document goes through lifecycle states from (for example) "Draft" to "Approved", its content may change from version to version. When querying documents, Vault only searches the latest version by default. Finding information contained in previous versions requires additional syntax added to the query string.

The ALLVERSIONS and LATESTVERSION syntax allows you to query:

  • All versions of a document
  • All versions of a document while filtering for the latest version which matches a specific search criteria (even if the matching document is not the latest version)
  • All versions of a document while filtering for steady state versions (even if the steady state version is not the latest version)

Top

Introduction, Setup, and Basic Keyword Searches

For the following examples, assume that a particular document has the following versions and keywords contained within the document content:

Version State Keywords in document content Notes
0.1 Draft Insulin Added "Insulin"
0.2 Draft Insulin, Contraindications Added "Contraindications"
1.0 Approved (superseded steady state version) Insulin, Dosage Removed "Contraindications"; Added "Dosage"
1.1 Draft Insulin, Dosage No change
2.0 Approved (latest steady state version) Insulin, Prescribing Removed "Dosage"; Added "Prescribing"
2.1 Draft Insulin, Prescribing No change
2.2 Draft (latest version) Insulin, Formulary Removed "Prescribing"; Added "Formulary"

Before using the FIND operator, we'll first query the document using the WHERE filter on the document name:

SELECT id, minor_version_number__v, major_version_number__v FROM documents WHERE name__v = 'Wonderdrug Information'

Example JSON Response:

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 1,
        "total": 1
    },
    "data": [
        {
            "id": 534,
            "minor_version_number__v": 2,
            "major_version_number__v": 2
        }
    ]
}

The major_version_number__v (2) in the API response represents version 2.0 in the UI. This is the latest steady state (approved) version, having replaced (superseded) the previous steady state version (1.0). The minor_version_number__v (2) in the API response represents version 1.2, 2.2, etc., depending on major version number. In this case, the minor version number is 2.2. This is the latest version.

Next, we'll use the FIND operator to search for documents with the keywords "Contraindications" or "Dosage" or "Prescribing" in the content:

SELECT id, minor_version_number__v, major_version_number__v FROM documents FIND 'Contraindications OR Dosage OR Prescribing' SCOPE content
{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "find": "Contraindications OR Dosage",
        "limit": 1000,
        "offset": 0,
        "size": 0,
        "total": 0
    },
    "data": []
}

The query above returns no results because "Contraindications" was removed from the document content when it changed from version 0.2 to 0.3, "Dosage" was removed when it changed from version 1.1 to 1.2, and "Prescribing" was removed when it changed from version 2.1 to 2.2. This illustrates the point that when querying documents without using "version parameters" (described below), Vault only searches the latest version.

To further illustrate this point, we'll perform a search for a word we know is in the latest version:

SELECT id, minor_version_number__v, major_version_number__v FROM documents FIND 'Formulary' SCOPE content
{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "find": "Formulary",
        "limit": 1000,
        "offset": 0,
        "size": 1,
        "total": 1
    },
    "data": [
        {
            "id": 534,
            "minor_version_number__v": 2,
            "major_version_number__v": 2
        }
    ]
}

The query above found our document in version 2.2 (latest). For most document searches, the latest version is what you want to query anyway. Once a new version is created, the old versions (minor or major) are typically no longer relevant. There are times, however, that you need to find an older version of a document.

Top

Search for Keywords Across All Document Versions

In Vault, the ALLVERSIONS syntax is placed in the FROM clause to indicate that you want to search all versions of the documents (minor and major). Here's an example:

SELECT id, minor_version_number__v, major_version_number__v FROM ALLVERSIONS documents FIND 'Dosage' SCOPE content
{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "find": "Dosage",
        "limit": 1000,
        "offset": 0,
        "size": 2,
        "total": 2
    },
    "data": [
        {
            "id": 534,
            "minor_version_number__v": 1,
            "major_version_number__v": 1
        },
        {
            "id": 534,
            "minor_version_number__v": 0,
            "major_version_number__v": 1
        }
    ]
}

The query above found our keyword in versions 1.1 and 1.0. Recall from the table above that these are the only versions in which "Dosage" was present. Performing the same query for "Contraindications" finds it in version 0.2 and "Prescribing" in versions 2.1 and 2.0. If we queried "Insulin" (present in all seven versions), the response would look similar to the one above, with seven data records representing each document version.

Top

Search for the Latest Version in which Keywords Exist

In Vault, the LATESTVERSION syntax is placed in the SELECT clause to indicate that you want to find the only the latest version in which the keyword is found. You must include the ALLVERSIONS syntax in the string as well. Here's an example:

SELECT LATESTVERSION id, minor_version_number__v, major_version_number__v FROM ALLVERSIONS documents FIND 'Dosage' SCOPE content
{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "find": "Dosage",
        "limit": 1000,
        "offset": 0,
        "size": 1,
        "total": 1
    },
    "data": [
        {
            "id": 534,
            "minor_version_number__v": 1,
            "major_version_number__v": 1
        }
    ]
}

The query above found the latest version (1.1) in which our keyword exists. Contrast this result with the previous, which found our keyword in two versions. Using LATESTVERSION or sorting through results is a matter of choice. It's most useful when the keyword exists in many different versions and you only want the latest.

Top

Searching Document States

Searching document states is really just another way to search across document versions. The following examples use the same document information used in the examples above and listed in the table at the top of this article.

Note: For those using API v9.0 and later, the document state parameters must be entered in the following format:

SELECT fields FROM documents WHERE status__v = steadystate()
SELECT fields FROM documents WHERE status__v = supersededstate()
SELECT fields FROM documents WHERE status__v = obsoletestate()

Note: For those using API v8.0 and earlier, the document state parameters must be entered in the following format:

SELECT fields FROM documents WHERE STEADYSTATE() = true
SELECT fields FROM documents WHERE SUPERSEDEDSTATE() = true
SELECT fields FROM documents WHERE OBSOLETESTATE() = true

The query response in API v8.0 and earlier will also differ from those shown here. Refer to the appropriate API Reference for more information.

Top

Search for Documents which are in a Steady State

SELECT LATESTVERSION id, minor_version_number__v, major_version_number__v FROM ALLVERSIONS documents  FIND 'Insulin' SCOPE content WHERE status__v = steadystate()
{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "find": "Insulin",
        "limit": 1000,
        "offset": 0,
        "size": 1,
        "total": 1
    },
    "data": [
        {
            "id": 534,
            "minor_version_number__v": 0,
            "major_version_number__v": 2
        }
    ]
}

The query above found our keyword "Insulin" in version 2.0 of the document. You'll recall from the table above and examples in the previous section, that the keyword "Insulin" exists in all versions of the document, including both major (steady state) versions 1.0 and 2.0. The reason this query only returned version 2.0 is that we included the LATESTVERSION syntax.

When performing document state searches, you only need to include LATESTVERSION or ALLVERSIONS when you specifically want the query to include documents matching those parameters.

What about the other keywords?

If we performed the same query as above, substituting "Insulin" for:

  • Contraindication - No results. It doesn't exist in any steady state versions.
  • Dosage - No results. It doesn't exist in the latest steady state version. However, if you removed LATESTVERSION from the SELECT clause and kept ALLVERSIONS in the FROM clause, Vault would find it in major version 1.0 and display those results.
  • Prescribing - Same results as "Insulin". It exists in the latest steady state version (2.0).
  • Formulary - No results. It doesn't exist in any steady state versions.

Top

Search for Documents which are in a Superseded State

SELECT LATESTVERSION id, minor_version_number__v, major_version_number__v FROM ALLVERSIONS documents  FIND 'Insulin' SCOPE content WHERE status__v = supersededstate()
{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "find": "Insulin",
        "limit": 1000,
        "offset": 0,
        "size": 1,
        "total": 1
    },
    "data": [
        {
            "id": 534,
            "minor_version_number__v": 0,
            "major_version_number__v": 1
        }
    ]
}

The query above found our keyword "Insulin" in version 1.0 of the document. Version 1.0 was the latest steady state version until it was superseded by version 2.0. The same result would be returned using the keyword "Dosage". No result would be returned for any of the other keywords in the table above.

Top

Search for Documents which are in an Obsolete State

For all the examples above, we used a document which was actively being used and progressing through draft and approved states. For the example below, let's assume that document has now been retired from use and its status changed to "obsolete". When a document moves to this state, all versions of the document also move to the obsolete state. This applies all settings (security, entry actions, user actions) for that state to each version of the document.

SELECT id, minor_version_number__v, major_version_number__v FROM ALLVERSIONS documents  FIND 'Insulin' SCOPE content WHERE status__v = obsoletestate()
{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 7,
        "total": 7
    },
    "data": [
        {
            "id": 534,
            "minor_version_number__v": 1,
            "major_version_number__v": 2
        },
        {
            "id": 534,
            "minor_version_number__v": 0,
            "major_version_number__v": 2
        },
        {
            "id": 534,
            "minor_version_number__v": 1,
            "major_version_number__v": 1
        },
        {
            "id": 534,
            "minor_version_number__v": 2,
            "major_version_number__v": 0
        },
        {
            "id": 534,
            "minor_version_number__v": 0,
            "major_version_number__v": 1
        },
        {
            "id": 534,
            "minor_version_number__v": 1,
            "major_version_number__v": 0
        },
        {
            "id": 534,
            "minor_version_number__v": 2,
            "major_version_number__v": 2
        }
    ]
}

If we had included LATESTVERSION in the query string, this would have returned only version 2.2.

As a follow-up, let's query the document to retrieve its current status:

SELECT id, name__v, status__v FROM documents WHERE id = 534
{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 1,
        "total": 1
    },
    "data": [
        {
            "id": 534,
            "name__v": "Wonderdrug Information",
            "status__v": "Obsolete"
        }
    ]
}

Top

Searching Archived Documents

As of API v15.0, you can search for documents in your vault which have been "archived." Learn more.

Note: Archiving documents is currently only available in select vaults and must be enabled by Support.

To search for all archived documents:

SELECT id, name__v FROM archived_documents

To search for all versions of archived documents:

SELECT id, name__v FROM ALLVERSIONS archived_documents

To search for the latest versions of archived documents:

SELECT id, name__v FROM LATESTVERSION archived_documents

To search for archived documents, filtering by document metadata:

SELECT id, name__v FROM archived_documents FIND ('insulin') SCOPE Properties

To search for archived documents, filtering by document content:

SELECT id, name__v FROM archived_documents FIND ('insulin') SCOPE CONTENT

To search for archived documents, filtering by document metadata and content:

SELECT id, name__v FROM archived_documents FIND ('insulin') SCOPE ALL

Learn about Query Syntax & Structure.

Top