1. Home
  2. OpenKM 6.3 - CE
  3. Development
  4. API description
  5. OKMSearch
  1.  

OKMSearch

Basics

Almosts all methods use QueryParams. Here there're some tips about how using it.

VariablesTypeAllow wildcardsRestrictionsDescription

domain

long

No.

Available values:

  • QueryParams.DOCUMENT
  • QueryParams.FOLDER
  • QueryParams.MAIL

By default the value is set to QueryParams.DOCUMENT.

For searching documents and folders use value:

(QueryParams.DOCUMENT | QueryParams.FOLDER)

Restricts the search to a node types.

author

String

No.

Value must be a valid userId.

Filters by creator user.

name

String

Yes.

 

Filters by node name.

keywords

Set<String>

Yes.

 

Filters by keywords.

categories

Set<String>

No.

Values should be a category UUID, not use path value.

Filters by categories.

content

  

Yes.

  

Filters by binary content.

mimeType

  

No.

Value should be a valid and registered MIME type.

Only can be applied to documents node.

 Filters by document MIME type.

path

  

No.

When empty is used by default "/okm:root" node.

Value should be a valid path, not use a UUID value.

Filters by a folder.

lastModifiedFrom

Calendar

No.

  

Filters by nodes created after a date.

lastModifiedTo

Calendar

No.

  

Filters by nodes created before a date.

mailSubject

String

Yes.

Only apply to mail nodes.

Filters by mail subject field.

mailFrom

String

Yes.

Only apply to mail nodes.

 Filters by mail from field.

mailTo

  

Yes.

Only apply to mail nodes.

Filters by mail to field.

properties

Map<String, String>

Yes on almost.

On metadata field values like "date" can not be applied wilcards.

The map of the properties is composed of pairs:

('metadata_field_name','metada_field_value")

For example:

Map<String, String> properties = new HashMap();
properties.put("okp:consulting.name", "name value");

Filtering by range of dates:

Calendar to = Calendar.getInstance(); // today
to.set(0, Calendar.HOUR);
to.set(0, Calendar.MINUTE);
to.set(0, Calendar.SECOND);
to.set(0, Calendar.MILLISECOND);
Calendar from = (Calendar) to.clone();
from.add(-3, Calendar.DATE); // three days before
Map<String,String> properties = new HashMap<>();
properties.put("okp:consulting.date", ISO8601.formatBasic(from)+","+ISO8601.formatBasic(to));

When filtering by range of dates you must set both values ( from and to ), otherwise the filter will be ignored from the  OpenKM side.

To filtering by a metadata field of type multiple like this:

<select label="Multiple" name="okp:consulting.multiple" type="multiple">
  <option label="One" value="one"/>
  <option label="Two" value="two"/>
  <option label="Three" value="three" />
</select>

You should do:

properties.put("okp:consulting.multiple", "one;two");

Where "one" and "two" are valid values and character ";" is used as separator.

Filters by metadata group values.

The search operation is done only by AND logic.

Wildcard examples:

VariableExampleDescription

name

test*.html

Any document that starts with characters "test" and ends with characters ".html"

name

test?.html

Any document that starts with characters "test" followed by a single character and ends with characters ".html"

name

?test*

Any of the documents where the first character doesn't matter, but is followed by the characters, "test".

Methods

findByContent

Description:

MethodReturn valuesDescription

findByContent(String content)

List<QueryResult>

Returns a list of results filtered by the value of the content parameter.

The method only searches among all documents, it does not take in consideration any other kind of nodes.

Example:

package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.bean.QueryResult;

public class Test {
    public static void main(String[] args) {
        try {
            for (QueryResult qr : OKMSearch.getInstance().findByContent(null, "test")) {
                System.out.println(qr);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

findByName

Description:

MethodReturn valuesDescription

findByName(String token, String words)

List<QueryResult>

Returns a list of results filtered by the value of the name parameter.

The method only searches among all documents, it does not take in consideration any other kind of nodes.

Example:

package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.bean.QueryResult;

public class Test {
    public static void main(String[] args) {
        try {
            for (QueryResult qr : OKMSearch.getInstance().findByName(null, "test*.html")) {
                System.out.println(qr);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

findByKeywords

Description:

MethodReturn valuesDescription

findByKeywords(String token, Set<String> words)

List<QueryResult>

Returns a list of results filtered by the values of the keywords parameter.

The method only searches among all documents, it does not take in consideration any other kind of nodes.

Example:

package com.openkm;

import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;

import com.openkm.api.OKMSearch;
import com.openkm.bean.QueryResult;

public class Test {
    public static void main(String[] args) {
        try {
            Set<String> keywords = new HashSet<>(Arrays.asList("test"));
            for (QueryResult qr : OKMSearch.getInstance().findByKeywords(null, keywords)) {
                System.out.println(qr);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

find

Description:

MethodReturn valuesDescription

find(String token, QueryParams params)

List<QueryResult>

Returns a list of results filtered by the values of the queryParams parameter.

Example:

package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.bean.QueryResult;
import com.openkm.dao.bean.QueryParams;

public class Test {
    public static void main(String[] args) {
        try {
            QueryParams qParams = new QueryParams();
            qParams.setDomain(QueryParams.DOCUMENT);
            qParams.setName("test*.html");
            for (QueryResult qr : OKMSearch.getInstance().find(null, qParams)) {
                System.out.println(qr);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

findPaginated

Description:

MethodReturn valuesDescription

findPaginated(String token, QueryParams params, int offset, int limit)

ResultSet

Returns a list of paginated results filtered by the values of the queryParams parameter.

The parameter "limit" and "offset" allows you to retrieve just a portion of the results of a query.

  • The parameter "limit" is used to limit the number of results returned.
  • The parameter "offset" is used to skip that many results before the beginning to return results.

For example if your query has 1000 results, but you only want to return the first 10, you should use these values:

  • limit=10
  • offset=0

Now suppose you want to show the results from 11-20, you should use these values:

  • limit=10
  • offset=10

Example:

package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.bean.QueryResult;
import com.openkm.bean.ResultSet;
import com.openkm.dao.bean.QueryParams;

public class Test {
    public static void main(String[] args) {
        try {
            QueryParams qParams = new QueryParams();
            qParams.setDomain(QueryParams.DOCUMENT);
            qParams.setName("test*.html");
            ResultSet rs = OKMSearch.getInstance().findPaginated(null, qParams, 20, 10);
            System.out.println("Total results:"+rs.getTotal());
            
            for (QueryResult qr : rs.getResults()) {
                System.out.println(qr);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

saveSearch

Description:

MethodReturn valuesDescription

saveSearch(String token, QueryParams params)

Long

Saves a search parameters.
The variable queryName of the parameter params, should have to be initialized. 
package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.dao.bean.QueryParams;

public class Test {
    public static void main(String[] args) {
        try {
            QueryParams qParams = new QueryParams();
            qParams.setDomain(QueryParams.DOCUMENT);
            qParams.setName("test*.html");
            // Save the search to be used later
            qParams.setQueryName("sample search");
            OKMSearch.getInstance().saveSearch(null, qParams);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

updateSearch

Description:

MethodReturn valuesDescription

updateSearch(String token, QueryParams params)

 void

Saves a search parameters.

Only can be updated as a saved search created by the same user user who's executing the method.

 
package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.dao.bean.QueryParams;

public class Test {
    public static void main(String[] args) {
        try {
            for (QueryParams qParams : OKMSearch.getInstance().getAllSearchs(null)) {
                if (qParams.getQueryName().equals("sample search")) {
                    // Change some value.
                    qParams.setName("admin*.html");
                    OKMSearch.getInstance().updateSearch(null, qParams);
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getSearch

Description:

MethodReturn valuesDescription

getSearch(String token, int qpId)

 QueryParams

Gets saved search parameters.

Only can be updated as a saved search created by the same user user who's executing the method.

 
package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.dao.bean.QueryParams;

public class Test {
    public static void main(String[] args) {
        try {
            int qpId = 12; // Some valid search id
            QueryParams qParams = OKMSearch.getInstance().getSearch(null, qpId);
            System.out.println(qParams);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getAllSearchs

Description:

MethodReturn valuesDescription

getAllSearchs(String token)

 List<QueryParams>

Retrieves a list of all saved search parameters.

Only can be updated as a saved search created by the same user user who's executing the method.

 
package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.dao.bean.QueryParams;

public class Test {
    public static void main(String[] args) {
        try {
            for (QueryParams qParams : OKMSearch.getInstance().getAllSearchs(null)) {
                System.out.println(qParams);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

deleteSearch

Description:

MethodReturn valuesDescription

deleteSearch(String token, long qpId)

void

Deletes a saved search parameters.

Only can be updated as a saved search created by the same user user who's executing the method.

 
package com.openkm;

import com.openkm.api.OKMSearch;

public class Test {
    public static void main(String[] args) {
        try {
            int qpId = 12; // Some valid search id
            OKMSearch.getInstance().deleteSearch(null, qpId);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getKeywordMap

Description:

MethodReturn valuesDescription

getKeywordMap(String token, List<String> filter)

Map<String, Integer>

Returns a map of keywords with its count value filtered by other keywords.

Example:

  • Doc1.txt has keywords "test", "one", "two".
  • Doc2.txt has keywords "test", "one"
  • Doc3.txt has keywords "test", "three".

The results filtering by "test" -> "one", "two", "three".

The results filtering by "one" -> "test", "two".

The results filtering by "two" -> "test", "one".

The results filtering by "three" -> "test".

The results filtering by "one" and "two" -> "test"

 
package com.openkm;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;

import com.openkm.api.OKMSearch;

public class Test {
    public static void main(String[] args) {
        try {
         // All keywords without filtering
            System.out.println("Without filtering");
            Map<String, Integer> keywords = OKMSearch.getInstance().getKeywordMap(null, new ArrayList<String>());

            for (String key : keywords.keySet()) {
                System.out.println(key + " is used :" + keywords.get(key) );
            }
            
            // Keywords filtered
            System.out.println("Filtering");
            keywords = OKMSearch.getInstance().getKeywordMap(null, Arrays.asList("test"));

            for (String key : keywords.keySet()) {
                System.out.println(key + " is used :" + keywords.get(key) );
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getCategorizedDocuments

Description:

MethodReturn valuesDescription

getCategorizedDocuments(String token, String categoryId)

List<Document>

Retrieves a list of all documents related with a category.
The values of the categoryId parameter should be a category folder UUID or path. 
package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.bean.Document;

public class Test {
    public static void main(String[] args) {
        try {
            for (Document doc : OKMSearch.getInstance().getCategorizedDocuments(null, "/okm:categories/invoices")) {
                System.out.println(doc);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getCategorizedFolders

Description:

MethodReturn valuesDescription

getCategorizedFolders(String token, String categoryId)

List<Folder>

Retrieves a list of all folders related with a category.
The values of the categoryId parameter should be a category folder UUID or path. 
package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.bean.Folder;

public class Test {
    public static void main(String[] args) {
        try {
            for (Folder fld : OKMSearch.getInstance().getCategorizedFolders(null, "/okm:categories/invoices")) {
                System.out.println(fld);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getCategorizedMails

Description:

MethodReturn valuesDescription

getCategorizedMails(String token, String categoryId)

List<Mail>

Retrieves a list of all mails related with a category.
The values of the categoryId parameter should be a category folder UUID or path. 
package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.bean.Mail;

public class Test {
    public static void main(String[] args) {
        try {
            for (Mail mail : OKMSearch.getInstance().getCategorizedMails(null, "/okm:categories/invoices")) {
                System.out.println(mail);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getDocumentsByKeyword

Description:

MethodReturn valuesDescription

getDocumentsByKeyword(String token, String keyword)

List<Document>

Retrieves a list of all documents related with a keyword.

 
package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.bean.Document;

public class Test {
    public static void main(String[] args) {
        try {
            for (Document doc : OKMSearch.getInstance().getDocumentsByKeyword(null, "test")) {
                System.out.println(doc);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getFoldersByKeyword

Description:

MethodReturn valuesDescription

getFoldersByKeyword(String token, String keyword)

List<Folder>

Retrieves a list of all folders related with a keyword.

 
package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.bean.Folder;

public class Test {
    public static void main(String[] args) {
        try {
            for (Folder fld : OKMSearch.getInstance().getFoldersByKeyword(null, "test")) {
                System.out.println(fld);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getMailsByKeyword

Description:

MethodReturn valuesDescription

getMailsByKeyword(String token, String keyword)

List<Mail>

Retrieves a list of all mails related with a keyword.

 
package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.bean.Mail;

public class Test {
    public static void main(String[] args) {
        try {
            for (Mail mail : OKMSearch.getInstance().getMailsByKeyword(null, "test")) {
                System.out.println(mail);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getDocumentsByPropertyValue

Description:

MethodReturn valuesDescription

getDocumentsByPropertyValue(String token, String group, String property, String value

List<Document>

Retrieves a list of all documents related with a metadata field value.

 
package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.bean.Document;

public class Test {
    public static void main(String[] args) {
        try {
            for (Document doc : OKMSearch.getInstance().getDocumentsByPropertyValue(null, "okg:consulting","okp:consulting.name","value")) {
                System.out.println(doc);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getFoldersByPropertyValue

Description:

MethodReturn valuesDescription

getFoldersByPropertyValue(String token, String group, String property, String value

List<Folder>

Retrieves a list of all folders related with a metadata field value.

 
package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.bean.Folder;

public class Test {
    public static void main(String[] args) {
        try {
            for (Folder fld : OKMSearch.getInstance().getFoldersByPropertyValue(null, "okg:consulting","okp:consulting.name","value")) {
                System.out.println(fld);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getMailsByPropertyValue

Description:

MethodReturn valuesDescription

getMailsByPropertyValue(String token, String group, String property, String value

List<Mail>

Retrieves a list of all mails related with a metadata field value.

 
package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.bean.Mail;

public class Test {
    public static void main(String[] args) {
        try {
            for (Mail mail : OKMSearch.getInstance().getMailsByPropertyValue(null, "okg:consulting","okp:consulting.name","value")) {
                System.out.println(mail);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

findSimpleQuery

Description:

MethodReturn valuesDescription

findSimpleQuery(String token, String statement)

List<QueryResult>

Returns a list of results filtered by the values of the statement parameter.

The syntax to use in the statement parameter is the pair 'field:value'. For example:

  • "name:grial" is filtering field name by word grial.

More information about lucene sintaxis at Lucene query syntax.

 
package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.bean.QueryResult;

public class Test {
    public static void main(String[] args) {
        try {
            for (QueryResult qr : OKMSearch.getInstance().findSimpleQuery(null, "name:grial")) {
                System.out.println(qr);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

findSimpleQueryPaginated

Description:

MethodReturn valuesDescription

findSimpleQueryPaginated(String token, String statement, int offset, int limit)

ResultSet

Returns a list of paginated results filtered by the values of the statement parameter.

The syntax to use in the statement parameter is the pair 'field:value'. For example:

  • "name:grial" is filtering field name by word grial.

More information about lucene sintaxis at Lucene query syntax.

The parameter "limit" and "offset" allows you to retrieve just a portion of the results of a query.

  • The parameter "limit" is used to limit the number of results returned.
  • The parameter "offset" is used to skip that many results before the beginning to return results.

For example if your query has 1000 results, but you only want to return the first 10, you should use these values:

  • limit=10
  • offset=0

Now suppose you want to show the results from 11-20, you should use these values:

  • limit=10
  • offset=10
 
package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.bean.QueryResult;
import com.openkm.bean.ResultSet;

public class Test {
    public static void main(String[] args) {
        try {
            ResultSet rs = OKMSearch.getInstance().findSimpleQueryPaginated(null, "name:grial", 20, 10);
            System.out.println("Total results:"+rs.getTotal());
            
            for (QueryResult qr : rs.getResults()) {
                System.out.println(qr);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

findMoreLikeThis

Description:

MethodReturn valuesDescription

findMoreLikeThis(String token, String uuid, int maxResults)

ResultSet

Returns a list of documents that are considered similar by search engine.

The uuid is a document UUID.

The max value is used to limit the number of results returned.

The method can only be used with documents.

 
package com.openkm;

import com.openkm.api.OKMSearch;
import com.openkm.bean.QueryResult;
import com.openkm.bean.ResultSet;

public class Test {
    public static void main(String[] args) {
        try {
            ResultSet rs = OKMSearch.getInstance().findMoreLikeThis(null, "f123a950-0329-4d62-8328-0ff500fd42db", 100);
            System.out.println("Total results:"+rs.getTotal());
            
            for (QueryResult qr : rs.getResults()) {
                System.out.println(qr);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}