Zach Olivare - 2020 Jul 19
The story that Microsoft docs, for some reason, refuse to tell you
So you've got a Functions project, and you've created a Cosmos DB in the azure portal, now how do you connect them?
The way that the interaction of writing to a database from within an Azure Function is supposed to work is via a binding.
You create an entry in your
function.json file for an output binding to Cosmos DB:
And then you use the
context.bindings object to write to the property you specified in the
name field above:
But that DOES NOT WORK!
All that happens when this code runs is a vertex with no data is created in the Cosmos DB.
Why is that? Because Microsoft does not currently support binding to a Cosmos DB using the Gremlin API.
I'm guessing that the SQL API came out before the Gremlin API, and was at the time this documentation was written the only available API. So the Microsoft MVPs that wrote these "documentation" articles weren't aware that they should state that what they were doing was specific to SQL.
Now that I've hopefully helped you avoid the pitfall that stole hours of my life, what we're actually going to do is make use of the gremlin NPM package.
Remember that because we're developing our functions locally, we can install NPM packages and then the
node_modules directory automatically gets pushed into Azure with your function code so that everything continues to work in the cloud.
After installing the NPM package, first thing you need to do is define some configuration variables about your database. At the root of your project create a
SharedCode directory and inside of that create a
You can find each of these data in your Cosmos DB on the Azure portal:
endpointcan be found on the Overview tab
primaryKeycan be found on the Keys tab
databasecan be found on the Data Explorer tab, it is the top level item in the DATA section
collectioncan be found by expanding the (just described) database to show its collections
Once you have the configuration down, you can then use that information to create a Gremlin client that you'll use to communicate with the database:
Client has been crated, you can finally create your first vertex!
As you can see, the syntax here is quite unfortunate. You have to craft this query as a string. Values with quotes around them get treated as strings, and values without quotes get interpreted as keys in the object that you pass as the second argument to
In this post, we've seen that Microsoft doesn't exactly make it easy to work with Cosmos DB's Gremlin API inside of an Azure Function. It doesn't have any bindings, and doesn't support the backend features necessary to make it easy to work with the gremlin NPM package either.
As I hinted at earlier, I've created a wrapper around the gremlin NPM package to make it easier to work with Cosmos' Gremlin API; it's called gremlin-cosmos.