CBL-5180: Implement Array Index API

CouchbaseLite.xcodeproj/project.pbxproj

@@ -1772,6 +1772,14 @@
 		AE83D0852C0637ED0055D2CF /* CBLIndexUpdater.mm in Sources */ = {isa = PBXBuildFile; fileRef = AE83D0832C0637ED0055D2CF /* CBLIndexUpdater.mm */; };
 		AE83D0862C0637ED0055D2CF /* CBLIndexUpdater.h in Headers */ = {isa = PBXBuildFile; fileRef = AE83D0822C0637ED0055D2CF /* CBLIndexUpdater.h */; settings = {ATTRIBUTES = (Private, ); }; };
 		AE83D0872C0637ED0055D2CF /* CBLIndexUpdater.mm in Sources */ = {isa = PBXBuildFile; fileRef = AE83D0832C0637ED0055D2CF /* CBLIndexUpdater.mm */; };
+		AEC806B72C89EA68001C9723 /* CBLArrayIndexConfiguration.h in Headers */ = {isa = PBXBuildFile; fileRef = AEC806B52C89EA68001C9723 /* CBLArrayIndexConfiguration.h */; settings = {ATTRIBUTES = (Public, ); }; };
+		AEC806B82C89EA68001C9723 /* CBLArrayIndexConfiguration.m in Sources */ = {isa = PBXBuildFile; fileRef = AEC806B62C89EA68001C9723 /* CBLArrayIndexConfiguration.m */; };
+		AEC806B92C89EA68001C9723 /* CBLArrayIndexConfiguration.m in Sources */ = {isa = PBXBuildFile; fileRef = AEC806B62C89EA68001C9723 /* CBLArrayIndexConfiguration.m */; };
+		AEC806BA2C89EA68001C9723 /* CBLArrayIndexConfiguration.h in Headers */ = {isa = PBXBuildFile; fileRef = AEC806B52C89EA68001C9723 /* CBLArrayIndexConfiguration.h */; settings = {ATTRIBUTES = (Private, ); }; };
+		AEC806BB2C89EA68001C9723 /* CBLArrayIndexConfiguration.h in Headers */ = {isa = PBXBuildFile; fileRef = AEC806B52C89EA68001C9723 /* CBLArrayIndexConfiguration.h */; settings = {ATTRIBUTES = (Public, ); }; };
+		AEC806BC2C89EA68001C9723 /* CBLArrayIndexConfiguration.m in Sources */ = {isa = PBXBuildFile; fileRef = AEC806B62C89EA68001C9723 /* CBLArrayIndexConfiguration.m */; };
+		AEC806BD2C89EA68001C9723 /* CBLArrayIndexConfiguration.m in Sources */ = {isa = PBXBuildFile; fileRef = AEC806B62C89EA68001C9723 /* CBLArrayIndexConfiguration.m */; };
+		AEC806BE2C89EA68001C9723 /* CBLArrayIndexConfiguration.h in Headers */ = {isa = PBXBuildFile; fileRef = AEC806B52C89EA68001C9723 /* CBLArrayIndexConfiguration.h */; settings = {ATTRIBUTES = (Private, ); }; };
 		AECD5A162C0E21D900B1247E /* CBLIndexUpdater+Internal.h in Headers */ = {isa = PBXBuildFile; fileRef = AECD5A0F2C0E21D900B1247E /* CBLIndexUpdater+Internal.h */; };
 		AECD5A172C0E21D900B1247E /* CBLIndexUpdater+Internal.h in Headers */ = {isa = PBXBuildFile; fileRef = AECD5A0F2C0E21D900B1247E /* CBLIndexUpdater+Internal.h */; };
 /* End PBXBuildFile section */
@@ -2792,6 +2800,8 @@
 		AE5803D72B9B5B2A001A1BE3 /* WordEmbeddingModel.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = WordEmbeddingModel.swift; sourceTree = "<group>"; };
 		AE83D0822C0637ED0055D2CF /* CBLIndexUpdater.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = CBLIndexUpdater.h; sourceTree = "<group>"; };
 		AE83D0832C0637ED0055D2CF /* CBLIndexUpdater.mm */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.objcpp; path = CBLIndexUpdater.mm; sourceTree = "<group>"; };
+		AEC806B52C89EA68001C9723 /* CBLArrayIndexConfiguration.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = CBLArrayIndexConfiguration.h; sourceTree = "<group>"; };
+		AEC806B62C89EA68001C9723 /* CBLArrayIndexConfiguration.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = CBLArrayIndexConfiguration.m; sourceTree = "<group>"; };
 		AECD59F92C0E137200B1247E /* CBLQueryIndex+Internal.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = "CBLQueryIndex+Internal.h"; sourceTree = "<group>"; };
 		AECD5A0F2C0E21D900B1247E /* CBLIndexUpdater+Internal.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = "CBLIndexUpdater+Internal.h"; sourceTree = "<group>"; };
 /* End PBXFileReference section */
@@ -4331,6 +4341,8 @@
 				1A3471482671C87F0042C6BA /* CBLFullTextIndexConfiguration.m */,
 				1A34715C2671C9230042C6BA /* CBLValueIndexConfiguration.h */,
 				1A34715D2671C9230042C6BA /* CBLValueIndexConfiguration.m */,
+				AEC806B52C89EA68001C9723 /* CBLArrayIndexConfiguration.h */,
+				AEC806B62C89EA68001C9723 /* CBLArrayIndexConfiguration.m */,
 			);
 			name = Index;
 			sourceTree = "<group>";
@@ -4432,6 +4444,7 @@
 				932EA56D2061FF7E00EDB667 /* CBLVersion.h in Headers */,
 				9384D80A1FC3F75700FE89D8 /* CBLQueryArrayFunction.h in Headers */,
 				937F01DD1EFB1A2500060D64 /* CBLSessionAuthenticator.h in Headers */,
+				AEC806BA2C89EA68001C9723 /* CBLArrayIndexConfiguration.h in Headers */,
 				27E35A9C1E8C522200E103F9 /* CBLReplicator.h in Headers */,
 				9388CBEE21BF727A005CA66D /* CBLLog.h in Headers */,
 				939B1B5B2009C04100FAA3CB /* CBLQueryVariableExpression.h in Headers */,
@@ -4658,6 +4671,7 @@
 				9343EFDD207D611600F19A89 /* CBLTrustCheck.h in Headers */,
 				9343EFDE207D611600F19A89 /* CBLBasicAuthenticator.h in Headers */,
 				1A34714B2671C8800042C6BA /* CBLFullTextIndexConfiguration.h in Headers */,
+				AEC806BB2C89EA68001C9723 /* CBLArrayIndexConfiguration.h in Headers */,
 				9343EFE0207D611600F19A89 /* CBLJSON.h in Headers */,
 				9388CBFD21BF74FD005CA66D /* CBLConsoleLogger.h in Headers */,
 				9343EFE1207D611600F19A89 /* CBLDocumentChange.h in Headers */,
@@ -4923,6 +4937,7 @@
 				9343F11E207D61AB00F19A89 /* CBLWebSocket.h in Headers */,
 				9343F11F207D61AB00F19A89 /* MYErrorUtils.h in Headers */,
 				40FC1C162B928ADD00394276 /* CBLListenerCertificateAuthenticator+Internal.h in Headers */,
+				AEC806BE2C89EA68001C9723 /* CBLArrayIndexConfiguration.h in Headers */,
 				69002EBF234E695600776107 /* CBLErrorMessage.h in Headers */,
 				9343F121207D61AB00F19A89 /* MYLogging.h in Headers */,
 				40FC1B632B9287BD00394276 /* CBLTLSIdentity.h in Headers */,
@@ -5031,6 +5046,7 @@
 				934F4CA91E241FB500F90659 /* CBLCoreBridge.h in Headers */,
 				9384D8091FC3F75700FE89D8 /* CBLQueryArrayFunction.h in Headers */,
 				274B4F8121A4D51100B2B4E6 /* CBLQuery+JSON.h in Headers */,
+				AEC806B72C89EA68001C9723 /* CBLArrayIndexConfiguration.h in Headers */,
 				931C14661EAAD6610094F9B2 /* CBLMutableDictionaryFragment.h in Headers */,
 				934A27B71F30E810003946A7 /* CBLQuantifiedExpression.h in Headers */,
 				9383A58F1F1EE9550083053D /* CBLQueryResultSet+Internal.h in Headers */,
@@ -5523,7 +5539,7 @@
 					};
 					9343EF2A207D611600F19A89 = {
 						DevelopmentTeam = N2Q372V7W2;
-						LastSwiftMigration = 1340;
+						LastSwiftMigration = 1540;
 					};
 					9343F135207D61EC00F19A89 = {
 						DevelopmentTeam = N2Q372V7W2;
@@ -5554,7 +5570,7 @@
 					9398D9111E03434200464432 = {
 						CreatedOnToolsVersion = 8.1;
 						DevelopmentTeam = N2Q372V7W2;
-						LastSwiftMigration = 1340;
+						LastSwiftMigration = 1540;
 						ProvisioningStyle = Automatic;
 					};
 					9398D91A1E03434200464432 = {
@@ -6012,6 +6028,7 @@
 				938CDF201E807F45002EE790 /* DataSource.swift in Sources */,
 				93CED8CB20488BD400E6F0A4 /* DocumentChange.swift in Sources */,
 				9386852921B09C5400BB1242 /* DocumentReplication.swift in Sources */,
+				AEC806B92C89EA68001C9723 /* CBLArrayIndexConfiguration.m in Sources */,
 				93EC42D41FB3801E00D54BB4 /* CBLValueIndex.m in Sources */,
 				937A69061F0731230058277F /* CBLQueryFunction.m in Sources */,
 				93FD616420204E3600E7F6A1 /* CBLIndexBuilder.m in Sources */,
@@ -6374,6 +6391,7 @@
 				9343EF72207D611600F19A89 /* CBLQueryVariableExpression.m in Sources */,
 				9343EF73207D611600F19A89 /* CBLQuery.mm in Sources */,
 				9343EF74207D611600F19A89 /* CBLArray.mm in Sources */,
+				AEC806BC2C89EA68001C9723 /* CBLArrayIndexConfiguration.m in Sources */,
 				9343EF75207D611600F19A89 /* CBLQuantifiedExpression.m in Sources */,
 				9343EF76207D611600F19A89 /* CBLCoreBridge.mm in Sources */,
 				9343EF77207D611600F19A89 /* CBLQueryLimit.m in Sources */,
@@ -6525,6 +6543,7 @@
 				9343F053207D61AB00F19A89 /* PropertyExpression.swift in Sources */,
 				9343F054207D61AB00F19A89 /* CBLChangeNotifier.m in Sources */,
 				9388CC0221BF74FD005CA66D /* CBLConsoleLogger.m in Sources */,
+				AEC806BD2C89EA68001C9723 /* CBLArrayIndexConfiguration.m in Sources */,
 				1AAFB691284A266F00878453 /* Scope.swift in Sources */,
 				40FC1C642B928C1600394276 /* MessageEndpointBridge.swift in Sources */,
 				9343F055207D61AB00F19A89 /* CBLDocumentChangeNotifier.mm in Sources */,
@@ -6896,6 +6915,7 @@
 				9383A5861F1EE7C00083053D /* CBLQueryResultSet.mm in Sources */,
 				93E17F0C1ED3AC8100671CA1 /* CBLDatabaseChange.m in Sources */,
 				9388CC0921BF750E005CA66D /* CBLFileLogger.mm in Sources */,
+				AEC806B82C89EA68001C9723 /* CBLArrayIndexConfiguration.m in Sources */,
 				933208171E77415E000D9993 /* CBLQueryOrdering.m in Sources */,
 				931C14541EAABCE70094F9B2 /* CBLFragment.m in Sources */,
 				9380C6F01E15B8C20011E8CB /* CBLMutableDocument.mm in Sources */,

Objective-C/CBLArrayIndexConfiguration.h

@@ -0,0 +1,66 @@
+//
+//  CBLArrayIndexConfiguration.h
+//  CouchbaseLite
+//
+//  Copyright (c) 2024 Couchbase, Inc All rights reserved.
+//
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//  http://www.apache.org/licenses/LICENSE-2.0
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+//
+
+#import <Foundation/Foundation.h>
+#import <CouchbaseLite/CBLIndexConfiguration.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ Configuration for indexing property values within nested arrays in documents, 
+ intended for use with the UNNEST query.
+ */
+
+@interface CBLArrayIndexConfiguration : CBLIndexConfiguration
+
+/**
+ Path to the array, which can be nested.
+ */
+
+@property (nonatomic, readonly) NSString* path;
+
+/**
+ The expressions representing the values within the array to be indexed.
+ */
+
+@property (nonatomic, readonly, nullable) NSArray<NSString*>* expressions;
+
+/**
+ Initializes the configuration with paths to the nested array
+ and the optional expressions for the values within the arrays to be indexed.
+ @param path Path to the array, which can be nested to be indexed.
+ @note Use "[]" to represent a property that is an array of each nested
+ array level. For a single array or the last level array, the "[]" is optional.
+
+ For instance, use "contacts[].phones" to specify an array of phones within
+ each contact.
+ @param expressions An optional array of strings, where each string
+ represents an expression defining the values within the array
+ to be indexed. If the array specified by the path contains
+ scalar values, this parameter can be null.
+
+ @return The CBLArrayIndexConfiguration object.
+ */
+
+- (instancetype) initWithPath: (NSString*)path
+                  expressions: (nullable NSArray<NSString*>*)expressions;
+
+@end
+
+NS_ASSUME_NONNULL_END

Objective-C/CBLArrayIndexConfiguration.m

@@ -0,0 +1,62 @@
+//
+//  CBLArrayIndexConfiguration.m
+//  CouchbaseLite
+//
+//  Copyright (c) 2024 Couchbase, Inc All rights reserved.
+//
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//  http://www.apache.org/licenses/LICENSE-2.0
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+//
+
+#import "CBLArrayIndexConfiguration.h"
+#import "CBLIndexConfiguration+Internal.h"
+
+@implementation CBLArrayIndexConfiguration
+
+@synthesize path=_path, expressions=_expressions;
+
+- (instancetype) initWithPath: (NSString*) path
+                  expressions: (nullable NSArray<NSString*>*)expressions {
+
+    if(!expressions) {
+        self = [super initWithIndexType: kC4ArrayIndex
+                            expressions: @[@""]];
+    }
+
+    if ([expressions count] == 0) {
+        [NSException raise: NSInvalidArgumentException format:
+         @"Expressions cannot be empty "];
+    }
+
+    self = [super initWithIndexType: kC4ArrayIndex
+                        expressions: expressions];
+
+    if (self) {
+        _path = path;
+        _expressions = expressions;
+    }
+
+    return self;
+}
+
+- (instancetype) initWithPath: (NSString*)path {
+    self = [self initWithPath: path expressions: nil];
+    return self;
+}
+
+- (C4IndexOptions) indexOptions {
+    C4IndexOptions c4options = { };
+    //c4options.unnestPath = _path;
+    return c4options;
+}
+
+@end

Objective-C/CBLFullTextIndexConfiguration.m

@@ -27,7 +27,8 @@ @implementation CBLFullTextIndexConfiguration
 - (instancetype) initWithExpression: (NSArray<NSString*>*)expressions
                       ignoreAccents: (BOOL)ignoreAccents
                            language: (NSString* __nullable)language {
-    self = [super initWithIndexType: kC4FullTextIndex expressions: expressions];
+    self = [super initWithIndexType: kC4FullTextIndex
+                        expressions: expressions];
     if (self) {
         // there is no default 'ignoreAccents', since its NOT an optional argument.
         _ignoreAccents = ignoreAccents;

Objective-C/CouchbaseLite.h

@@ -27,6 +27,7 @@ FOUNDATION_EXPORT const unsigned char CouchbaseLiteVersionString[];
 
 #import <CouchbaseLite/CBLArray.h>
 #import <CouchbaseLite/CBLArrayFragment.h>
+#import <CouchbaseLite/CBLArrayIndexConfiguration.h>
 #import <CouchbaseLite/CBLAuthenticator.h>
 #import <CouchbaseLite/CBLBasicAuthenticator.h>
 #import <CouchbaseLite/CBLBlob.h>

Objective-C/Exports/CBL.txt

@@ -21,6 +21,7 @@
 #  Classes:
 .objc_class_name_CBLArray
 .objc_class_name_CBLAuthenticator
+.objc_class_name_CBLArrayIndexConfiguration
 .objc_class_name_CBLBasicAuthenticator
 .objc_class_name_CBLBlob
 .objc_class_name_CBLCollection

Objective-C/Exports/Generated/CBL.exp

@@ -1,6 +1,7 @@
 # GENERATED BY generate_exports.sh -- DO NOT EDIT
 
 .objc_class_name_CBLArray
+.objc_class_name_CBLArrayIndexConfiguration
 .objc_class_name_CBLAuthenticator
 .objc_class_name_CBLBasicAuthenticator
 .objc_class_name_CBLBlob

Objective-C/Exports/Generated/CBL_EE.exp

@@ -1,6 +1,7 @@
 # GENERATED BY generate_exports.sh -- DO NOT EDIT
 
 .objc_class_name_CBLArray
+.objc_class_name_CBLArrayIndexConfiguration
 .objc_class_name_CBLAuthenticator
 .objc_class_name_CBLBasicAuthenticator
 .objc_class_name_CBLBlob

Swift/CouchbaseLiteSwift.private.modulemap

@@ -20,6 +20,7 @@
 framework module CouchbaseLiteSwift_Private {
     header "CBLArray.h"
     header "CBLArrayFragment.h"
+    header "CBLArrayIndexConfiguration.h"
     header "CBLAuthenticator.h"
     header "CBLBasicAuthenticator.h"
     header "CBLBlob.h"

Swift/IndexConfiguration.swift

@@ -69,6 +69,38 @@ public struct ValueIndexConfiguration: IndexConfiguration, IndexConfigConvertabl
     }
 }
 
+/// Configuration for indexing property values within nested arrays in documents,
+/// intended for use with the UNNEST query.
+public struct ArrayIndexConfiguration: IndexConfiguration, IndexConfigConvertable {
+    /// Path to the array, which can be nested.
+    public let path: String
+
+    ///  The expressions representing the values within the array to be indexed.
+    public let expressions: [String]?
+
+    /// Initializes the configuration with paths to the nested array and the optional
+    /// expressions for the values within the arrays to be indexed.
+    /// - Parameter path Path to the array, which can be nested to be indexed.
+    /// - Note Use "[]" to represent a property that is an array of each nested array level.
+    ///     For a single array or the last level array, the "[]" is optional.
+    ///     For instance, use "contacts[].phones" to specify an array of phones within each contact.
+    /// - Parameter expressions An optional array of strings, where each string
+    ///     represents an expression defining the values within the array to be indexed.
+    ///     If the array specified by the path contains scalar values, this parameter can be null.
+    /// - Returns The ArrayIndexConfiguration object.
+    public init(path: String, _ expressions: [String]?) {
+        self.path = path
+        self.expressions = expressions
+    }
+
+    // MARK: Internal
+
+    func toImpl() -> CBLIndexConfiguration {
+        return CBLArrayIndexConfiguration(path: path, expressions: expressions)
+    }
+}
+
+
 // MARK: Internal
 
 protocol IndexConfigConvertable {