Document Id changes (#14)

Co-authored-by: jeffrey-elliott <jeffrey.elliott@gmail.com>
Co-authored-by: Steve Hewitt <45011981+stephenatsembit@users.noreply.github.com>

Author: a-random-steve

index.md

@@ -8,7 +8,9 @@ This C# Client Library simplifies using the DataStax Data API to manage and inte
 
 # Installation
 
-// TODO: NuGet instructions
+```
+dotnet add package DataStax.AstraDB.DataApi --prerelease
+```
 
 # Quickstart
 
@@ -17,7 +19,7 @@ This C# Client Library simplifies using the DataStax Data API to manage and inte
 var client = new DataApiClient("YourTokenHere");
 
 //connect to a database
-var database = client.GetDatabase("YourDatabaseUrlHere");
+var database = client.GetDatabase("YourAPIEndpointHere");
 
 //create a new collection
 var collection = await database.CreateCollectionAsync<SimpleObject>("YourCollectionNameHere");

src/DataStax.AstraDB.DataApi/Core/CollectionDefinition.cs

@@ -14,6 +14,10 @@
  * limitations under the License.
  */
 
+using DataStax.AstraDB.DataApi.SerDes;
+using System;
+using System.Collections.ObjectModel;
+using System.Reflection;
 using System.Text.Json.Serialization;
 
 namespace DataStax.AstraDB.DataApi.Core;
@@ -40,6 +44,36 @@ public class CollectionDefinition
     /// </summary>
     [JsonPropertyName("indexing")]
     public IndexingOptions Indexing { get; set; }
+
+    internal static CollectionDefinition Create<T>()
+    {
+        Type type = typeof(T);
+        PropertyInfo idProperty = null;
+        DocumentIdAttribute idAttribute = null;
+
+        CollectionDefinition definition = new();
+
+        foreach (var property in type.GetProperties())
+        {
+            var attr = property.GetCustomAttribute<DocumentIdAttribute>();
+            if (attr != null)
+            {
+                idProperty = property;
+                idAttribute = attr;
+                break;
+            }
+        }
+
+        if (idProperty != null)
+        {
+            if (idAttribute.DefaultIdType.HasValue)
+            {
+                definition.DefaultId = new DefaultIdOptions() { Type = idAttribute.DefaultIdType.Value };
+            }
+        }
+
+        return definition;
+    }
 }
 
 

src/DataStax.AstraDB.DataApi/Core/CommandOptions.cs

@@ -44,7 +44,7 @@ public class CommandOptions
     /// <summary>
     /// The token to use for authentication
     /// </summary>
-    public string Token { get; internal set; }
+    public string Token { get; set; }
 
     /// <summary>
     /// The destination datastore.

src/DataStax.AstraDB.DataApi/Core/Database.cs

@@ -73,9 +73,10 @@ public class Database
     private readonly string _apiEndpoint;
     private readonly DataApiClient _client;
     private readonly string _urlPostfix = "";
-    private readonly DatabaseCommandOptions _dbCommandOptions;
     private readonly Guid _id;
 
+    private DatabaseCommandOptions _dbCommandOptions;
+
     internal string ApiEndpoint => _apiEndpoint;
     internal DataApiClient Client => _client;
     internal Guid DatabaseId => _id;
@@ -98,6 +99,17 @@ internal Database(string apiEndpoint, DataApiClient client, DatabaseCommandOptio
         _id = (Guid)GetDatabaseIdFromUrl(_apiEndpoint);
     }
 
+    /// <summary>
+    /// Set the active keyspace to use for all subsequent operations (can be overridden in each method call via an overload with the <see cref="DatabaseCommandOptions"/> parameter)
+    /// </summary>
+    /// <param name="keyspace"></param>
+    public void UseKeyspace(string keyspace)
+    {
+        var commandOptions = _dbCommandOptions ?? new DatabaseCommandOptions();
+        commandOptions.Keyspace = keyspace;
+        _dbCommandOptions = commandOptions;
+    }
+
     ///<summary>
     ///Synchronous version of <see cref="DoesCollectionExistAsync(string)"/>.
     ///</summary>
@@ -409,10 +421,11 @@ public Task<Collection<T, TId>> CreateCollectionAsync<T, TId>(string collectionN
 
     private async Task<Collection<T>> CreateCollectionAsync<T>(string collectionName, CollectionDefinition definition, DatabaseCommandOptions options, bool runSynchronously) where T : class
     {
-        object payload = definition == null ? new
+        if (definition == null)
         {
-            name = collectionName
-        } : new
+
+        }
+        object payload = new
         {
             name = collectionName,
             options = definition
@@ -424,10 +437,11 @@ private async Task<Collection<T>> CreateCollectionAsync<T>(string collectionName
 
     private async Task<Collection<T, TId>> CreateCollectionAsync<T, TId>(string collectionName, CollectionDefinition definition, DatabaseCommandOptions options, bool runSynchronously) where T : class
     {
-        object payload = definition == null ? new
+        if (definition == null)
         {
-            name = collectionName
-        } : new
+            definition = CollectionDefinition.Create<T>();
+        }
+        object payload = new
         {
             name = collectionName,
             options = definition

src/DataStax.AstraDB.DataApi/DataAPIClient.cs

@@ -169,20 +169,22 @@ public Database GetDatabase(string apiEndpoint)
     }
 
     /// <summary>
-    /// Gets an instance of the <see cref="Database"/> class given the API Endpoint and the keyspace to connect to.
+    /// Gets an instance of the <see cref="Database"/> class given the API Endpoint of the database to connect to, a token to use, and optionally a keyspace.
+    /// If the keyspace is not provided the default keyspace will be used.
     /// </summary>
     /// <param name="apiEndpoint">The API endpoint of the database.</param>
-    /// <param name="keyspace">The keyspace to connect to.</param>
+    /// <param name="token">The specific token to use for this database connection.</param>
+    /// <param name="keyspace">Optional: The keyspace to connect to.</param>
     /// <returns>An instance of the <see cref="Database"/> class.</returns>
     /// <example>
     /// <code>
     /// var client = new DataApiClient("token");
     /// var database = client.GetDatabase("https://1ae8dd5d-19ce-452d-9df8-6e5b78b82ca7-us-east1.apps.astra.datastax.com", "myKeyspace");
     /// </code>
     /// </example>
-    public Database GetDatabase(string apiEndpoint, string keyspace)
+    public Database GetDatabase(string apiEndpoint, string token, string keyspace = null)
     {
-        var dbOptions = new DatabaseCommandOptions() { Keyspace = keyspace };
+        var dbOptions = new DatabaseCommandOptions() { Token = token, Keyspace = keyspace };
         return GetDatabase(apiEndpoint, dbOptions);
     }
 
@@ -229,7 +231,8 @@ public Database GetDatabase(Guid databaseId)
     /// Gets an instance of a <see cref="Database"/> based on the database Id, set to the provided keyspace.
     /// </summary>
     /// <param name="databaseId">The Guid of the database.</param>
-    /// <param name="keyspace">The keyspace to use for the database commands.</param>
+    /// <param name="token">The specific token to use for this database connection.</param>
+    /// <param name="keyspace">Optional: The keyspace to use for the database commands.</param>
     /// <returns>An instance of the <see cref="Database"/> class.</returns>
     /// <example>
     /// <code>
@@ -241,9 +244,9 @@ public Database GetDatabase(Guid databaseId)
     ///      Using a Guid instead of the Database API endpoint requires an extra API call to lookup the appropriate database.
     ///      If you want to avoid this, use an overload that accepts the API endpoint (<see cref="GetDatabase(string, string)"/>).
     /// </remarks>
-    public Database GetDatabase(Guid databaseId, string keyspace)
+    public Database GetDatabase(Guid databaseId, string token, string keyspace = null)
     {
-        var dbOptions = new DatabaseCommandOptions() { Keyspace = keyspace };
+        var dbOptions = new DatabaseCommandOptions() { Keyspace = keyspace, Token = token };
         return GetDatabase(databaseId, dbOptions);
     }
 

src/DataStax.AstraDB.DataApi/DataStax.AstraDB.DataApi.csproj

@@ -7,7 +7,7 @@
     <LangVersion>10.0</LangVersion>
 
     <PackageId>DataStax.AstraDB.DataApi</PackageId>
-    <Version>1.0.0</Version>
+    <Version>1.0.2-beta</Version>
     <Authors>DataStax</Authors>
     <Company>DataStax</Company>
     <Description>Client library for accessing the DataStax Astra DB Data API from .NET applications.</Description>
@@ -19,7 +19,7 @@
     <RepositoryType>git</RepositoryType>
     <PackageLicenseExpression>Apache-2.0</PackageLicenseExpression>
     <PackageIcon>packageIcon.png</PackageIcon>
-    <Readme>README.md</Readme>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
   </PropertyGroup>
 
   <ItemGroup>

src/DataStax.AstraDB.DataApi/SerDes/DocumentConverter.cs

@@ -50,7 +50,6 @@ static DocumentConverter()
                 {
                     DocumentMappingField.Vectorize => DataApiKeywords.Vectorize,
                     DocumentMappingField.Vector => DataApiKeywords.Vector,
-                    DocumentMappingField.Id => DataApiKeywords.Id,
                     DocumentMappingField.Similarity => DataApiKeywords.Similarity,
                     _ => prop.Name
                 };
@@ -60,7 +59,8 @@ static DocumentConverter()
             }
             else
             {
-                if (prop.Name == DataApiKeywords.Id)
+                var idAttr = prop.GetCustomAttribute<DocumentIdAttribute>();
+                if (idAttr != null || prop.Name == DataApiKeywords.Id)
                 {
                     FieldMappings[prop] = DataApiKeywords.Id;
                     ReverseMappings[DataApiKeywords.Id] = prop;
@@ -131,6 +131,13 @@ public override void Write(Utf8JsonWriter writer, T value, JsonSerializerOptions
                         continue;
                     }
                 }
+
+                var documentIdAttr = prop.GetCustomAttribute<DocumentIdAttribute>();
+                if (documentIdAttr != null && propValue == null)
+                {
+                    continue;
+                }
+
                 writer.WritePropertyName(propertyName);
 
                 JsonSerializer.Serialize(writer, propValue, prop.PropertyType, options);

src/DataStax.AstraDB.DataApi/SerDes/DocumentIdAttribute.cs

@@ -0,0 +1,60 @@
+/*
+ * Copyright DataStax, Inc.
+ *
+ * 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.
+ */
+
+namespace DataStax.AstraDB.DataApi.SerDes;
+
+using DataStax.AstraDB.DataApi.Core;
+using System;
+
+/// <summary>
+/// Marks a property on a document as the unique ID
+/// </summary>
+[AttributeUsage(AttributeTargets.Property | AttributeTargets.Field, AllowMultiple = false)]
+public class DocumentIdAttribute : Attribute
+{
+    /// <summary>
+    /// If the database is going to auto-generate ids for inserted document, which type of ID should it generate?
+    /// </summary>
+    public DefaultIdType? DefaultIdType { get; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DocumentIdAttribute"/> class.
+    /// </summary>
+    /// <remarks>
+    /// 1. If you want the database to auto-generate Ids for the documents, please use the <see cref="DocumentIdAttribute(DefaultIdType)"/> overload.
+    /// When not specified, DefaultIdType.Uuid (UUID v4) will be used.
+    /// 2. Please note that the C# type used for the property/field that this attribute is assigned to must match the type associated
+    /// with the specified default ID (or you need to always pass in a value for the Id field).
+    /// </remarks>
+    public DocumentIdAttribute()
+    {
+
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DocumentIdAttribute"/> class.
+    /// </summary>
+    /// <param name="defaultIdType">The type of Id to auto-generate</param>
+    /// <remarks>
+    /// The C# type used for the property/field that this attribute is assigned to must match the type associated
+    /// with the specified default ID (or use the <see cref="DocumentIdAttribute()"/> constructor to not set a default type 
+    /// and always pass in a value for the Id field.
+    /// </remarks>
+    public DocumentIdAttribute(DefaultIdType defaultIdType)
+    {
+        DefaultIdType = defaultIdType;
+    }
+}

src/DataStax.AstraDB.DataApi/SerDes/DocumentMappingField.cs

@@ -21,8 +21,6 @@ namespace DataStax.AstraDB.DataApi.SerDes;
 /// </summary>
 public enum DocumentMappingField
 {
-    /// <summary>Serializes as "_id" for unique identifiers</summary>
-    Id,
     /// <summary>Serializes as "$vectorize" for a string to vectorize</summary>
     Vectorize,
     /// <summary>Serializes as "$vector" for vector data.</summary>

src/DataStax.AstraDB.DataApi/Utils/Extensions.cs

@@ -70,8 +70,8 @@ private static void BuildPropertyName(MemberExpression memberExpression, StringB
             {
                 name = jsonPropertyNameAttribute.Name;
             }
-            var attribute = propertyInfo.GetCustomAttribute<DocumentMappingAttribute>();
-            if (attribute != null && attribute.Field == DocumentMappingField.Id)
+            var attribute = propertyInfo.GetCustomAttribute<DocumentIdAttribute>();
+            if (attribute != null)
             {
                 name = DataApiKeywords.Id;
             }