Interface SearchInterface

The SearchInterface interface is used to search content in the DMU.

Please see Search.

The SearchInterface interfaces are created through the createSearch method.

The list of signals the SearchInterface may trigger is available in the SearchInterfaceSignal enumeration.

The search request is triggered through the search method. The result is not available right away, but the event SearchReady is triggered when the result of the SearchInterface is available. The result is available through the getSearchDocuments getGeometricInstanceIds and hasOtherResults functions.
As said in Search, the search result consists in a list of metadata documents that match the query (an array of SearchDocumentResultInterface from getSearchDocuments), it may be interesting to find the part instances, and the geometric instances that are linked to this search query. The DocumentIdConverterInterface fulfill this requirement.
The search result also provides right away the full list of geometric instance ids that are involved in the search result, regardless of the given cap included (the FULL list of all geometric instance ids that match the query are ALWAYS provided) with getGeometricInstanceIds.

Warning : there may be cases when the getSearchDocuments, getGeometricInstanceIds are not available such as when the SearchInterface is fetching data, i.e. when isRunning returns true, or when the SearchInterface has been cancelled, i.e. when isCancelled returns true.

A SearchInterface may be interrupted (cancelled) when the SearchInterface is running and cancelSearch is called. In such cases, the SearchCancelled signal is fired, and shortly after, SearchReady signal is fired, but getSearchDocuments and getGeometricInstanceIds will return undefined. Just call search with another (or the same) query to trigger a new search request.

If you call multiple times search before receiving the SearchReady, only one SearchReady will be sent with the content of the last call to search.

The syntax of the search is explained in the 3djuump infinite literal and search query language.

The search query must be provided with a maximum number of hits to help reduce server usage and bandwidth. If the search result is capped to this value then hasOtherResults returns true.

The search query is always limited to a filtering context (see Filtering Context) from the VisibilityContextInterface.

The search results may be filtered to include only a subset of the metadata inside the matching document, provided the search function is called with the list of metadata names to return.

/** 
 * Sample to explain how to make search requests.
 */
import {
    InfiniteEvent, SearchInterface, DocumentIdConverterInterface,
    VisibilityContextInterface, SearchDocumentResultInterface, DocumentIdResultInterface, DocumentIdConverterResultInterface,
    SearchInterfaceSignal, DocumentIdConverterInterfaceSignal, DataSessionInterface
} from 'generated/documentation/appinfiniteapi';

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// the filtering context for the whole DMU as been set previously
let lCurrentDMUVisibilityCtx : VisibilityContextInterface;

// the filtering context for the search has been set previously (can be lCurrentDMUVisibilityCtx)
let lSearchVisibilityCtx : VisibilityContextInterface;
// the string to search in documents
let lQueryString : string;
// the max number of results
const lMaxDocsToRetrieve : number = 50;

// create a search requester
const lSearch : SearchInterface = lDataSession.createSearch();

// to get actual results from a search request :
// the search requester gets result in the form of documents,
// in a second step, the user may enquire the server to know the 
// relevant `part instance ids`
// the DocumentIdConverterInterface is there to make the conversion between 
// a document id and the actual `part instances`
const lDocumentIdConverter : DocumentIdConverterInterface = lDataSession.createDocumentIdConverter();

// When the search is ready, we check for errors
// we may find all the `geometric instance ids` in the search result
// we get the first found document
// and find the relevant `part instance ids` and `geometric instance ids`
const onSearchReady = (pEvent: InfiniteEvent) : void =>
{
    const lSearchInterface: SearchInterface = <SearchInterface>(pEvent.emitter);
    // make sure the search in no more running
    if (lSearchInterface.isRunning()) {
        console.assert(false, 'this should not happen');
        return;
    }
    // and make sure no error
    if (lSearchInterface.getLastError().length > 0) {
        return;
    }

    // get all the `geometric instance ids` of the search request
    const lGeometricInstanceIds: Uint32Array | undefined = lSearchInterface.getGeometricInstanceIds();
    if (lGeometricInstanceIds !== undefined)
    {
        console.log('all the geometric instances concerned by the search:' + lGeometricInstanceIds.length);
    }

    // and get the documents (content is filtered by the last parameter of SearchInterface.search)
    const lSearchResult: Array<SearchDocumentResultInterface> | undefined = lSearchInterface.getSearchDocuments();
    if (lSearchResult) {
        console.log('Search finished: ' + lSearchResult.length + ' result(s)');
        // do we have all documents, or are there more that were not included due to the search results capped to lMaxDocsToRetrieve ?
        if (lSearchInterface.hasOtherResults())
        {
            // some GUI code there perhaps ?
            console.log('Search was capped to ' + lMaxDocsToRetrieve);
        }
        if (lSearchResult.length > 0) {
            // get the `part instance ids` of the first document
            const lDocumentId: number = lSearchResult[0].getDocumentId();
            const lIsInVisibility : boolean = lSearchResult[0].isInVisibilityCtx();
            let lVisibilityCtxToUse : VisibilityContextInterface;
            if (lIsInVisibility)
            {
                console.log('retrieve document in visibility : ' + lDocumentId);
                // we will try here to find instances only in the search filtering context
                // but depending on your needs, you may use lCurrentDMUVisibilityCtx to extend the 
                // result to the `part instances` of the whole DMU, it is up to you
                // or make 2 requests, one in the search ctx, the other outside, or ....
                lVisibilityCtxToUse = lSearchVisibilityCtx;
            }
            else {
                // this case cannot happen if the third parameter to search is true
                console.log('retrieve document outside visibility : ' + lDocumentId);
                // in order to get results, we will make the conversion in the whole DMU filtering context
                // since this concerns `part instances` outside the search filtering context
                lVisibilityCtxToUse = lCurrentDMUVisibilityCtx;
            }
            // find the `part instance ids` and `geometric instance ids` of this document
            lDocumentIdConverter.convert(lDocumentId, lVisibilityCtxToUse);
        }
    }
};

// When the document `part instances` are found
// we get the relevant `part instance ids` and `geometric instance ids` of the requested document
const onDocumentIdConverterReady = (pEvent: InfiniteEvent) : void =>
{
    const lEventDocumentIdConverter: DocumentIdConverterInterface = <DocumentIdConverterInterface>(pEvent.emitter);
    // make sure the search in no more running
    if (lEventDocumentIdConverter.isRunning()) {
        console.assert(false, 'this should not happen');
        return;
    }
    if (lEventDocumentIdConverter.getLastError().length > 0) {
        return;
    }
    const lResult: DocumentIdConverterResultInterface | undefined = lEventDocumentIdConverter.getConversionResult();
    if (lResult)
    {
        const lDocumentIdConverterInstances: Array<DocumentIdResultInterface> = lResult.getConvertedInstances();
        const lPartInstanceIds: Uint32Array = new Uint32Array(lDocumentIdConverterInstances.length);

        for (let i = 0; i < lDocumentIdConverterInstances.length; ++i) {
            lPartInstanceIds[i] = lDocumentIdConverterInstances[i].getPartInstanceId();
        }
        console.log('documents converted :');
        console.log('Convert part instances to geometric instance ids: ' + JSON.stringify(lPartInstanceIds));
    }
};

// what to do when we get the results ?
lDocumentIdConverter.addEventListener(DocumentIdConverterInterfaceSignal.DocumentIdConverterReady, onDocumentIdConverterReady);
lSearch.addEventListener(SearchInterfaceSignal.SearchReady, onSearchReady);

// make a search request, and only retrieve the "PartNumber" metadata of the result documents
// we will get all the documents of the DMU (third parameter : false), but will get a hint of the 
// documents inside lSearchVisibilityCtx
// imit the results to lMaxDocsToRetrieve documents maximum
lSearch.search(lQueryString, lSearchVisibilityCtx, false, lMaxDocsToRetrieve, ['PartNumber']);

/** 
 * Sample to explain how to make asynchronous search requests.
 */
import {
    SearchInterface, DocumentIdConverterInterface,
    VisibilityContextInterface, SearchDocumentResultInterface, DocumentIdResultInterface,
    AsyncSearchResult, AsyncResultReason, AsyncSearchResultContent, AsyncDocumentIdConverterResultInterfaceResult,
    DataSessionInterface,
} from 'generated/documentation/appinfiniteapi';

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// the filtering context for the whole DMU as been set previously
let lCurrentDMUVisibilityCtx : VisibilityContextInterface;

// the filtering context for the search has been set previously (can be lCurrentDMUVisibilityCtx)
let lSearchVisibilityCtx : VisibilityContextInterface;
// the string to search in documents
let lQueryString : string;
// the max number of results
const lMaxDocsToRetrieve : number = 50;

// create a search requester
const lSearch : SearchInterface = lDataSession.createSearch();

// to get actual results from a search request :
// the search requester gets result in the form of documents,
// in a second step, the user may enquire the server to know the 
// relevant `part instance ids`
// the DocumentIdConverterInterface is there to make the conversion between 
// a document id and the actual `part instances`
const lDocumentIdConverter : DocumentIdConverterInterface = lDataSession.createDocumentIdConverter();

const triggerSearchRequest = async () : Promise<any> =>
{
    // make a search request, and only retrieve the "PartNumber" metadata of the result documents
    // we will get all the documents of the DMU (third parameter : false), but will get a hint of the 
    // documents inside lSearchVisibilityCtx
    // limit the results to lMaxDocsToRetrieve documents maximum
    const lResult : AsyncSearchResult = await lSearch.asyncSearch(lQueryString, lSearchVisibilityCtx, false, lMaxDocsToRetrieve, ['PartNumber']);

    if (lResult.reason !== AsyncResultReason.ARR_Success || lResult.value === undefined)
    {
        console.assert(false, 'this should not happen');
        return;
    }
    // When the search is ready, we check for errors
    // we may find all the `geometric instance ids` in the search result
    // we get the first found document
    // and find the relevant `part instance ids` and `geometric instance ids`

    const lSearchContent : AsyncSearchResultContent = lResult.value;
    // get all the `geometric instance ids` of the search request
    const lGeometricInstanceIds: Uint32Array | undefined = lSearchContent.geometricInstanceIds;
    if (lGeometricInstanceIds !== undefined)
    {
        console.log('all the geometric instances concerned by the search:' + lGeometricInstanceIds.length);
    }

    // and get the documents (content is filtered by the last parameter of SearchInterface.search)
    const lSearchResult: Array<SearchDocumentResultInterface> | undefined = lSearchContent.searchDocuments;
    if (!lSearchResult) {
        console.assert(false, 'this should not happen');
        return;
    }
    console.log('Search finished: ' + lSearchResult.length + ' result(s)');
    // do we have all documents, or are there more that were not included due to the search results capped to lMaxDocsToRetrieve ?
    if (lSearchContent.hasOtherResults)
    {
        // some GUI code there perhaps ?
        console.log('Search was capped to ' + lMaxDocsToRetrieve);
    }
    if (lSearchResult.length <= 0) {
        console.log('no document found');
        return;
    }
    // get the `part instance ids` of the first document
    const lDocumentId: number = lSearchResult[0].getDocumentId();
    const lIsInVisibility : boolean = lSearchResult[0].isInVisibilityCtx();
    let lVisibilityCtxToUse : VisibilityContextInterface;
    if (lIsInVisibility)
    {
        console.log('retrieve document in visibility : ' + lDocumentId);
        // we will try here to find instances only in the search filtering context
        // but depending on your needs, you may use lCurrentDMUVisibilityCtx to extend the 
        // result to the `part instances` of the whole DMU, it is up to you
        // or make 2 requests, one in the search ctx, the other outside, or ....
        lVisibilityCtxToUse = lSearchVisibilityCtx;
    }
    else {
        // this case cannot happen if the third parameter to search is true
        console.log('retrieve document outside visibility : ' + lDocumentId);
        // in order to get results, we will make the conversion in the whole DMU filtering context
        // since this concerns `part instances` outside the search filtering context
        lVisibilityCtxToUse = lCurrentDMUVisibilityCtx;
    }
    // find the `part instance ids` and `geometric instance ids` of this document
    const lConversion : AsyncDocumentIdConverterResultInterfaceResult = await lDocumentIdConverter.asyncConvert(lDocumentId, lVisibilityCtxToUse);

    // When the document `part instances` are found
    // we get the relevant `part instance ids` and `geometric instance ids` of the requested document
    if (lConversion.reason !== AsyncResultReason.ARR_Success || lConversion.value === undefined)
    {
        console.assert(false, 'this should not happen');
        return;
    }
    const lDocumentIdConverterInstances: Array<DocumentIdResultInterface> = lConversion.value.getConvertedInstances();
    const lPartInstanceIds: Uint32Array = new Uint32Array(lDocumentIdConverterInstances.length);

    for (let i = 0; i < lDocumentIdConverterInstances.length; ++i) {
        lPartInstanceIds[i] = lDocumentIdConverterInstances[i].getPartInstanceId();
    }
    console.log('documents converted :');
    console.log('Convert part instances to geometric instance ids: ' + JSON.stringify(lPartInstanceIds));
}

triggerSearchRequest();

See

• SearchInterfaceSignal
• SearchDocumentResultInterface