1 /* 2 * Copyright 2023 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.server.appsearch.external.localstorage; 18 19 import android.app.appsearch.SearchSpec; 20 21 import com.google.android.icing.proto.IcingSearchEngineOptions; 22 23 /** 24 * An interface exposing the optional config flags in {@link IcingSearchEngineOptions} used to 25 * instantiate {@link com.google.android.icing.IcingSearchEngine}, as well as other additional 26 * config flags for IcingSearchEngine. 27 */ 28 public interface IcingOptionsConfig { 29 // Defaults from IcingSearchEngineOptions proto 30 int DEFAULT_MAX_TOKEN_LENGTH = 30; 31 32 int DEFAULT_INDEX_MERGE_SIZE = 1048576; // 1 MiB 33 34 boolean DEFAULT_DOCUMENT_STORE_NAMESPACE_ID_FINGERPRINT = false; 35 36 float DEFAULT_OPTIMIZE_REBUILD_INDEX_THRESHOLD = 0.0f; 37 38 /** 39 * The default compression level in IcingSearchEngineOptions proto matches the 40 * previously-hardcoded document compression level in Icing (which is 3). 41 */ 42 int DEFAULT_COMPRESSION_LEVEL = 3; 43 44 boolean DEFAULT_USE_PREMAPPING_WITH_FILE_BACKED_VECTOR = false; 45 46 boolean DEFAULT_USE_PERSISTENT_HASH_MAP = false; 47 48 int DEFAULT_MAX_PAGE_BYTES_LIMIT = Integer.MAX_VALUE; 49 50 /** 51 * The maximum allowable token length. All tokens in excess of this size will be truncated to 52 * max_token_length before being indexed. 53 * 54 * <p>Clients may use this option to prevent unnecessary indexing of long tokens. Depending on 55 * the use case, indexing all of 'Supercalifragilisticexpialidocious' may be unnecessary - a 56 * user is unlikely to type that entire query. So only indexing the first n bytes may still 57 * provide the desired behavior without wasting resources. 58 */ getMaxTokenLength()59 int getMaxTokenLength(); 60 61 /** 62 * The size (measured in bytes) at which Icing's internal indices should be merged. Icing 63 * buffers changes together before merging them into a more compact format. When the buffer 64 * exceeds index_merge_size during a Put operation, the buffer is merged into the larger, more 65 * compact index. 66 * 67 * <p>This more compact index is more efficient to search over as the index grows larger and has 68 * smaller system health impact. 69 * 70 * <p>Setting a low index_merge_size increases the frequency of merges - increasing 71 * indexing-time latency and flash wear. Setting a high index_merge_size leads to larger 72 * resource usage and higher query latency. 73 */ getIndexMergeSize()74 int getIndexMergeSize(); 75 76 /** 77 * Whether to use namespace id or namespace name to build up fingerprint for 78 * document_key_mapper_ and corpus_mapper_ in document store. 79 */ getDocumentStoreNamespaceIdFingerprint()80 boolean getDocumentStoreNamespaceIdFingerprint(); 81 82 /** 83 * The threshold of the percentage of invalid documents at which to rebuild index during 84 * optimize. 85 * 86 * <p>We rebuild index if and only if |invalid_documents| / |all_documents| >= threshold. 87 * 88 * <p>Rebuilding the index could be faster than optimizing the index if we have removed most of 89 * the documents. Based on benchmarks, 85%~95% seems to be a good threshold for most cases. 90 */ getOptimizeRebuildIndexThreshold()91 float getOptimizeRebuildIndexThreshold(); 92 93 /** 94 * The level of gzip compression for documents in the Icing document store. 95 * 96 * <p>NO_COMPRESSION = 0, BEST_SPEED = 1, BEST_COMPRESSION = 9 97 */ getCompressionLevel()98 int getCompressionLevel(); 99 100 /** 101 * Whether to allow circular references between schema types for the schema definition. 102 * 103 * <p>Even when set to true, circular references are still not allowed in the following cases: 104 * 1. All edges of a cycle have index_nested_properties=true 2. One of the types in the cycle 105 * has a joinable property, or depends on a type with a joinable property. 106 */ getAllowCircularSchemaDefinitions()107 boolean getAllowCircularSchemaDefinitions(); 108 109 /** 110 * Flag for {@link com.google.android.icing.proto.SearchSpecProto}. 111 * 112 * <p>Whether to use the read-only implementation of IcingSearchEngine::Search. 113 * 114 * <p>The read-only version enables multiple queries to be performed concurrently as it only 115 * acquires the read lock at IcingSearchEngine's level. Finer-grained locks are implemented 116 * around code paths that write changes to Icing during Search. 117 */ getUseReadOnlySearch()118 boolean getUseReadOnlySearch(); 119 120 /** 121 * Flag for {@link com.google.android.icing.proto.IcingSearchEngineOptions}. 122 * 123 * <p>Whether or not to pre-map the potential memory region used by the PersistentHashMap. This 124 * will avoid the need to re-map the mmapping used by PersistentHashMap whenever the underlying 125 * storage grows. 126 */ getUsePreMappingWithFileBackedVector()127 boolean getUsePreMappingWithFileBackedVector(); 128 129 /** 130 * Flag for {@link com.google.android.icing.proto.IcingSearchEngineOptions}. 131 * 132 * <p>Whether or not to use the PersistentHashMap in the QualifiedIdTypeJoinableIndex. If false, 133 * we will use the old IcingDynamicTrie to store key value pairs. 134 */ getUsePersistentHashMap()135 boolean getUsePersistentHashMap(); 136 137 /** 138 * Flag for {@link com.google.android.icing.proto.ResultSpecProto}. 139 * 140 * <p>The maximum byte size to allow in a single page. This limit is only loosely binding. 141 * AppSearch will add results to the page until either 1) AppSearch has retrieved {@link 142 * SearchSpec#getResultCountPerPage()} results or 2) total size of the page exceeds this value. 143 * Therefore, AppSearch will always retrieve at least a single result, even if that result 144 * exceeds this limit. 145 */ getMaxPageBytesLimit()146 int getMaxPageBytesLimit(); 147 } 148