ASP.NET CRUD applications consist of create, read, update, and delete. In part 1, we set up a basic ASP.NET Core project. In part 2, we added the first read endpoint, using a SQL++ query against wishlist data.
Couchbase’s SQL++ is a powerful query language, containing all the best features of relational SQL, with a superset of features for querying JSON data.
However, SQL++ isn’t the only way to interact with data in Couchbase. In this post, we’ll explore using the key-value API.
Key-value vs SQL?
If you have a relational background, then you are likely accustomed to SQL being the only way to interact with data (even if you’re using a tool like Entity Framework Core, it’s still ultimately using SQL). One of the great features of a NoSQL database (like Couchbase) is that while SQL is available, there are other access methods available too. (Hence the backronym “Not Only SQL”).
For Couchbase, the most efficient way to access data is via key-value lookup. Every other index and query that Couchbase supports (SQL++, Full-Text Search, Analytics, Eventing, and more) are ultimately built upon or rely on the lowly key-value lookup.
The key-value API will give you the best performance, where:
-
- A key is specified, or
- Your code is given a key, or
- You can construct a key deterministically
Examples: when to use key-value
Here are some examples of when (and when NOT) to use the key-value API for reading:
| Use case | Key-value? | Why or why not? |
| Lookup a user with key “73892“ | Yes | Direct lookup |
| Lookup just the email address of a user with key “73892“ | Yes | Even if the user document is large, Couchbase has a key-based sub-document API, which allows you to retrieve a portion of the document. |
| Lookup a group of users with keys “73892“, “47212“, and “90491” | Yes | This may require multiple key lookup operations, but this still may be faster than using a SQL SELECT … WHERE … IN query. |
| Lookup the comments from a blog post | Maybe | If comments for a blog post are in a single document, and the blog post key is known, a blog post comment key can be constructed. E.g. blog post key is I-like-balloons, to get comments, use the key I-like-balloons::comments |
| Lookup all users from “Ohio“ | No | User’s state is likely a “secondary” attribute, not a key (multiple users can be from Ohio). This is a good use case for SQL++ |
| Search for products with “balloons” in their description | No | Descriptions are a secondary attribute, not a key (multiple products may have “balloons” in their description). This is a good use case for Full-Text Search (FTS) |
Note that Couchbase has a memory-first architecture. The built-in cache means that a key-value lookup will often be retrieving data directly from memory—microsecond latency, no waiting on the disk.
My rule of thumb is: use key-value API whenever possible, and then fall back to a more flexible option like SQL++ or Full-Text Search when necessary.
Create a Get CRUD endpoint
Let’s create an endpoint that uses the key-value API to retrieve a single item from the wishlist.
This endpoint will require the ID of the wishlist item to be given as a parameter:
|
1 2 3 4 5 6 7 8 9 10 11 |
[HttpGet] [Route("api/get/{id}")] public async Task<IActionResult> Get(Guid id) { var bucket = await _bucketProvider.GetBucketAsync("demo"); var collection = await bucket.CollectionAsync("wishlist"); var item = await collection.GetAsync(id.ToString()); return Ok(item.ContentAs<WishlistItem>()); } |
In this example, we don’t need a cluster object (like we did with SQL++), but we do need a collection object. Note that since the wishlist collection is in the _default scope, we can skip right past getting the scope and go directly from bucket to collection.
When the item is returned from GetAsync, it’s in an IGetResult object. Couchbase doesn’t store C# objects, it stores JSON. So, to serialize to a WishlistItem object, use item.ContentAs<WishlistItem>.
This API gives you flexibility: a document returned from Couchbase could be serialized to WishlistItem here and perhaps AmazonWishlistItem in another part of the application.
Key-value in action
Execute the ASP.NET Core application and let’s look at the updated OpenAPI/Swagger page.
The endpoint /api/get/{id} under Gifts should now be listed. Expand that endpoint by clicking on it. Unlike the /api/getall endpoint, this one requires a parameter: the ID of the wishlist item that you want to get.
If you don’t remember one of the GUIDs, you can execute /api/getall first and copy one of them, or use: “31c9cc33-8dfe-440c-bd1b-bb038939d2e0” (which was the ID I gave to the Joey Votto jersey). Click Try it out, paste that ID, and click Execute:
Notice that in the response, the ID returned is null. This is because, as I explained in part 2, Couchbase stores the ID as metadata. In this situation, that’s not a big deal. The ID was given as a parameter, so you could just assign that to the C# object being returned:
|
1 2 3 4 |
var itemObj = item.ContentAs<WishlistItem>(); itemObj.Id = Guid.Parse(id); return Ok(itemObj); |
Alternatively, if you don’t want to return ID at all, you could create a separate C# view class that only has name and use that with ContentAs.
What about validation and error handling?
How wise of you to ask! This endpoint is definitely not ready for production. What’s missing?
-
- Error handling: what if there’s an exception?
- Validation: what if the ID passed in is invalid?
- Authentication/authorization: what if the consumer of this API isn’t supposed to have read access?
- Logging: what if something doesn’t go quite right, and we want to examine the outcome later?
These are all important concerns. For most of these, ASP.NET Core has built-in functionality and/or popular 3rd party libraries available to help you. But make sure to check out Couchbase documentation on Handling Errors with the .NET SDK and Security Management Overview.
What’s next?
The ASP.NET Core project is connected to Couchbase Capella, and it is reading data via both SQL++ and the key-value API.
In the next blog post, we’ll look at creating and updating (“C” and “U”) data.
In the meantime, you should:
-
- Sign up for a Capella free-trial
- Check out the Couchbase Playground for .NET examples that you can run right in the browser.
