SearchKit

Overview

Functions are grouped according to the tasks you perform using them. For an alphabetical list of functions, go to the API index at the end of the document.

Overview

Search Kit is a powerful and streamlined C language framework for indexing and searching text in most human languages. It provides fast information retrieval in System Preferences, Address Book, Help Viewer, and Xcode. Apple’s Spotlight technology is built on top of Search Kit to provide content searching in Finder, Mail, and the Spotlight menu.

You can use Search Kit or Spotlight to provide similar functionality and powerful information-access capabilities within your Mac app. Search Kit is appropriate when you want your application to have full control over indexing and searching, and when your focus is file content. Search Kit is thread-safe and works with Cocoa and command-line tools.

Search Kit supports phrase searches, prefix/suffix/substring searches, Boolean searches, summarization, and relevance ranking. Search Kit uses Spotlight’s metadata importers when indexing documents and takes advantage of any additional importers available on a system.

Topics

Creating, Opening, and Closing Indexes

Search Kit performs its searches not on documents but on its indexes of documents. The functions in this group let your application create memory-based and persistent indexes. Indexes are initially empty. Functions in Managing Indexes let you add document content to these indexes.

SKIndexCreateWithURL

Creates a named index in a file whose location is specified with a CFURL object.

SKIndexCreateWithMutableData

Creates a named index stored in a CFMutableDataRef object.

SKIndexOpenWithData

Opens an existing, named index for searching only.

SKIndexOpenWithMutableData

Opens an existing, named index for searching and updating.

SKIndexOpenWithURL

Opens an existing, named index stored in a file whose location is specified with a CFURL object.

SKIndexClose

Closes an index.

SKIndexGetIndexType

Gets the category of an index.

SKIndexGetTypeID

Gets the type identifier for Search Kit indexes.

Managing Indexes

The functions in this section let your application add document content to (and remove document content from) indexes, work with memory- and disk-based indexes, and retrieve metadata from indexes.

SKIndexAddDocumentWithText

Adds a document URL (SKDocumentRef) object, and the associated document’s textual content, to an index.

SKIndexAddDocument

Adds location information for a file-based document, and the document’s textual content, to an index.

SKIndexFlush

Invokes all pending updates associated with an index and commits them to backing store.

SKIndexCompact

Invokes all pending updates associated with an index, compacts the index if compaction is needed, and commits all changes to backing store.

SKIndexGetDocumentCount

Gets the total number of documents represented in an index.

SKIndexGetMaximumDocumentID

Gets the highest-numbered document ID in an index.

SKIndexGetMaximumTermID

Gets the highest-numbered term ID in an index.

SKIndexDocumentIteratorCreate

Creates an index-based iterator for document URL objects (of type SKDocumentRef) owned by a parent document URL object.

SKIndexDocumentIteratorCopyNext

Obtains the next document URL object (of type SKDocumentRef) from an index using a document iterator.

SKIndexDocumentIteratorGetTypeID

Gets the type identifier for Search Kit document iterators.

SKIndexGetAnalysisProperties

Gets the text analysis properties of an index.

SKIndexMoveDocument

Changes the parent of a document URL object (of type SKDocumentRef) in an index.

SKIndexRemoveDocument

Removes a document URL object (of type SKDocumentRef) and its children, if any, from an index.

SKIndexRenameDocument

Changes the name of a document URL object (of type SKDocumentRef) in an index.

SKIndexSetMaximumBytesBeforeFlush

Not recommended. Sets the memory size limit for updates to an index, measured in bytes.

SKIndexGetMaximumBytesBeforeFlush

Not recommended. Gets the memory size limit for updates to an index, measured in bytes.

Working With Text Importers

Search Kit can import the textual content of file-based documents into indexes using the Spotlight metadata importers.

SKLoadDefaultExtractorPlugIns

Tells Search Kit to use the Spotlight metadata importers.

Working with Documents and Terms

From Search Kit’s perspective, a document is anything that contains text—an RTF document, a PDF file, a Mail message, an Address Book entry, an Internet URL, the result of a database query, and so on.

The functions in this section let your application create new document URL objects (SKDocumentRefs), retrieve metadata from documents, get information on document hierarchies, and work with documents and their terms in the context of Search Kit indexes.

SKDocumentCreateWithURL

Creates a document URL object (of type SKDocumentRef) from a CFURLRef object.

SKDocumentCreate

Creates a document URL object (of type SKDocumentRef) based on a scheme, parent, and name.

SKDocumentCopyURL

Builds a CFURLRef object from a document URL object (of type SKDocumentRef).

SKDocumentGetName

Gets the name of a document URL object (of type SKDocumentRef).

SKDocumentGetParent

Gets the parent of a document URL object (of type SKDocumentRef).

SKDocumentGetSchemeName

Gets the scheme name for a document URL object (of type SKDocumentRef).

SKDocumentGetTypeID

Gets the type identifier for Search Kit document URL objects.

SKIndexCopyDocumentForDocumentID

Obtains a document URL object (of type SKDocumentRef) from an index.

SKIndexCopyInfoForDocumentIDs

Gets document names and parent IDs based on document IDs.

SKIndexCopyDocumentRefsForDocumentIDs

Gets document URL objects (of type SKDocumentRef) based on document IDs.

SKIndexCopyDocumentURLsForDocumentIDs

Gets document URLs based on document IDs.

SKIndexCopyDocumentIDArrayForTermID

Obtains document IDs for documents that contain a given term.

SKIndexCopyTermIDArrayForDocumentID

Obtains the IDs for the terms of an indexed document.

SKIndexCopyTermStringForTermID

Obtains a term, specified by ID, from an index.

SKIndexGetTermIDForTermString

Gets the ID for a term in an index.

SKIndexSetDocumentProperties

Sets the application-defined properties of a document URL object (of type SKDocumentRef).

SKIndexCopyDocumentProperties

Obtains the application-defined properties of an indexed document.

SKIndexGetDocumentState

Gets the current indexing state of a document URL object (of type SKDocumentRef) in an index.

SKIndexGetDocumentTermCount

Gets the number of terms for a document in an index.

SKIndexGetDocumentTermFrequency

Gets the number of occurrences of a term in a document.

SKIndexGetTermDocumentCount

Gets the number of documents containing a given term represented in an index.

SKIndexGetDocumentID

Gets the ID of a document URL object (of type SKDocumentRef) in an index.

Fast Asynchronous Searching

SKSearchCreate

Creates an asynchronous search object for querying an index, and initiates search.

SKSearchFindMatches

Extracts search result information from a search object.

SKSearchCancel

Cancels an asynchronous search request.

SKSearchGetTypeID

Gets the type identifier for Search Kit search objects.

Working With Summarization

Search Kit’s Summarization functions supplant those in Apple’s Find by Content API.

SKSummaryCreateWithString

Creates a summary object based on a text string.

SKSummaryGetSentenceSummaryInfo

Gets detailed information about a body of text for constructing a custom sentence-based summary string.

SKSummaryGetParagraphSummaryInfo

Gets detailed information about a body of text for constructing a custom paragraph-based summary string.

SKSummaryGetSentenceCount

Gets the number of sentences in a summarization object.

SKSummaryGetParagraphCount

Gets the number of paragraphs in a summarization object.

SKSummaryCopySentenceAtIndex

Gets a specified sentence from the text in a summarization object.

SKSummaryCopyParagraphAtIndex

Gets a specified paragraph from the text in a summarization object.

SKSummaryCopySentenceSummaryString

Gets a text string consisting of a summary with, at most, the requested number of sentences.

SKSummaryCopyParagraphSummaryString

Gets a text string consisting of a summary with, at most, the requested number of paragraphs.

SKSummaryGetTypeID

Gets the type identifier for Search Kit summarization objects.

Legacy Support for Synchronous Searching

Developers should avoid using the functions listed in this section; instead, use the replacement functions that are recommended. Search Kit retains the functions in this section for backward compatibility.

SKSearchGroupCreate

Creates a search group as an array of references to indexes.

Deprecated
SKSearchGroupCopyIndexes

Obtains the indexes for a search group.

Deprecated
SKSearchGroupGetTypeID

Deprecated. Use asynchronous searching with SKSearchCreate instead, which does not employ search groups.

Deprecated
SKSearchResultsCreateWithDocuments

Finds documents similar to given example documents.

Deprecated
SKSearchResultsGetInfoInRange

Extracts information from a Search Kit query result.

Deprecated
SKSearchResultsCopyMatchingTerms

Obtains the terms in a document that match a query.

Deprecated
SKSearchResultsGetCount

Gets the total number of found items in a search.

Deprecated
SKSearchResultsGetTypeID

Gets the type identifier for Search Kit search results.

Deprecated
SKSearchResultsCreateWithQuery

Queries the indexes in a search group.

Deprecated

Callbacks

Developers should avoid using the callbacks listed in this section; instead, use SKSearchCreate and SKSearchFindMatches.

SKSearchResultsFilterCallBack

Deprecated. Use SKSearchCreate and SKSearchFindMatches instead, which do not use a callback.

Data Types

SKDocumentRef

Defines an opaque data type representing a document’s URL.

SKIndexDocumentIteratorRef

Defines an opaque data type representing an index-based document iterator.

SKIndexRef

Defines an opaque data type representing an index.

SKSearchRef

Defines an opaque data type representing a an asynchronous search.

SKSummaryRef

Defines an opaque data type representing summarization information.

SKDocumentID

Defines an opaque data type representing a lightweight document identifier.

SKSearchResultsRef

Deprecated. Use asynchronous searching with SKSearchCreate instead, which does not employ search groups.

SKSearchGroupRef

Deprecated. Use asynchronous searching with SKSearchCreate instead, which does not employ search groups.

Constants

Text Analysis Keys

Each of these constants is an optional key in a Search Kit index’s text analysis properties dictionary. The constant descriptions describe the corresponding values for each of these keys. These keys are declared in the Analysis.h header file.

SKDocumentIndexState

The indexing state of a document.

SKSearchOptions

Specifies the search options available for the SKSearchCreate function.

SKIndexType

Specifies the category of an index.

Deprecated Text Analysis Keys

Search Kit ignores the kSKLanguageTypes constant. It determines language directly by document content.

SKSearchType

Search Kit ignores the constants in this group. Use asynchronous searching with SKSearchCreate instead, which uses query syntax to determine search type.