DEV Community: Jared Short

From LEGO Bricks to Data Blocks: Adventures with PromptQL

Jared Short — Tue, 19 Nov 2024 14:20:38 +0000

Did you know that across all the LEGO Star Wars sets, there are 9113 unique pieces used?

If you were to build every single one of the Star Wars sets, you would have used 63,269 of the "Light Bluish Gray" color (#A0A5A9).

Occasionally, I stumble across unique data and interesting data sets that I want to explore. Usually I end up throwing them in a SQL database and poking around the schema and do some SQL queries here or there. Sometimes I can learn a lot just grepping my way through the files for keywords and doing some analysis of those results.

Given I like playing with data, LLMs and RAG (Retrieval-augmented generation) seem inescapable these days. Using the power of an LLM to ask more in-depth questions across a vectorized space has yielded some surprising results, but I struggle to trust it beyond basic discovery and toy use cases. Don't get me wrong, I do use these tools where I find they aid my process, however I am also cautious when adding new tools to any kind of feature or process, especially ones that can "hallucinate" (read: "lie to your face and not be at all sorry").

L(EGO)LLM

I recently found the LEGO data from Rebrickable Data is downloadable in bulk, and contains all sorts of data about LEGO sets, pieces, minifigures, and more.

There is a lot of CSV data here. Millions of records. And given most of it is just numbers and relationships, RAG seemed like the wrong tool. We aren't trying to search or extract semantic meaning from things like titles or comments or descriptions. We don't have much to use a strategy like text embedding to get vectors. In this case, we are trying to draw meaning between lots of relationships defined with joins on ids and aggregations. However, not all is lost. There's been a flurry of activity with Agents and Agentic tools in the LLM space. Basically, giving an LLM the ability to do things like create and run code, and some degree of "autonomy" to figure out issues.

I've been playing with a new tool called PromptQL from Hasura that leverages what they call "Agentic Data Access", that has an interesting twist on things. (Note: I was given early access and was working with the team to provide feedback and they sponsored some of my time to play with the tool). Building on the standardized data access layer that Hasura already enables, PromptQL is a data access agent that can understand your data schema, and then generates a query plan to access your data and perform computations on the fly. PromptQL isn't just RAG across a vector space. It is querying data straight out of things like Postgres, or MongoDB, or even totally non-SQL sources like GitHub APIs. The ability to make an optimal query plan as opposed to following a strict retrieval pipeline is what makes PromptQL truly powerful.

Back to our LEGO data. The schema is pretty simple, just a lot of data organized into meaningful relationships.

I wrote a simple script to download everything from the Rebrickable website and dump it into a Postgres database. Should be fairly simple to grab and run yourself if you want to do your own tinkering.

It's all about the Prompt(QL)

Once I had that done, I set up PromptQL to point to the database. The PromptQL docs are pretty good at explaining this.

Once done, I fired up the PromptQL interface, and if you have used any chat interface (or ChatGPT like app), you'll feel right at home.

For example, I wonder how many of those Star Wars sets have that Light Bluish Gray piece?

So how do I know I can even trust these results? Simple. I don't have to. Every single thing the Agentic actions of PromptQL are doing is backed by code that it shows me.

The question "How many different colors are there?" replies with the following:

To answer your question about the number of different colors, I'll need to query the Colors table in the database. Let me fetch that information for you.
Query Plan

Query the Colors table to count the number of distinct colors.

Retrieve the total count of colors.

Store the result in an artifact for easy reference.

Present the information to the user.

It then writes and executes the following code:

# Query to count the number of distinct colors
sql = """
SELECT COUNT(DISTINCT id) as color_count
FROM app.Colors
"""

# Execute the query
result = executor.run_sql(sql)

# Extract the color count
color_count = result[0]['color_count']

# Store the result in an artifact
executor.store_artifact(
    'color_count',
    'Total Number of LEGO Colors',
    'table',
    [{'Total Colors': color_count}]
)

# Print the result for verification
executor.print(f"Total number of colors: {color_count}")

Output:
SQL statement returned 1 rows.
Stored table artifact: identifier = 'color_count', title = 'Total Number of LEGO Colors', number of rows = 1, sample rows = [{'Total Colors': 267}]
Total number of colors: 267

I don't have to trust whatever it spins out of some semantic search and RAG. I can look at the actual SQL it put together, and go look at the actual data sources if I need to confirm things. I have a habit of checking the executed code blocks fairly often to sanity check things. This level of transparency is critical, in my opinion, towards debugging Agentic applications.

One of my favorite things to do, because it has knowledge of your schema, you can ask PromptQL what kinds of questions you should even be asking. For the LEGO data I have, it suggested trying the following things:

- Historical evolution of LEGO sets, tracking how piece counts and complexity have changed across decades
- Analysis of rare minifigures and unique parts that only appear in a single set
- Comparison between licensed themes (Star Wars, Harry Potter) and original LEGO themes in terms of popularity and complexity
- Distribution patterns of colors across sets, particularly looking at sets with the most diverse color palettes
- Deep dive into the most epic sets ever produced, ranked by piece count and build complexity

I actually tried the first question, PromptQL yielded some interesting bullet points.

Piece count explosion: From just 18.5 pieces per set (1950s) to 363.3 pieces (2020s) - a massive 1,863.8% increase
Color variety: Sets went from using 2.7 colors (1950s) to 13.9 colors (2020s) - a 414.8% increase
Production peak: The 2010s saw the highest number of set releases with 6,074 different sets
Temporary decline: The 1980s showed an unusual dip in both piece count and color complexity compared to the 1970s
Recent acceleration: The most dramatic increases in both metrics occurred in the 2010s and 2020s

You also aren't just strictly limited to questions answerable directly within the data. For instance, take things like GitHub issues. You can still leverage a typical LLM use case and ask for PromptQL to categorize things by say, the GitHub issue content. Ask for it to sort things into various priorities (high, medium, low) or different types of issue (support, bug, feature). PromptQL will then combine pulling stuff from your sources and then using an LLM to classify them and use those results in your output artifacts or additional steps.

Cool, but what can it do? (Real-world applications beyond plastic bricks)

I've actually played with hooking this up to GitHub issues, and some other data sources. While it has its rough edges, I've been able to accomplish all kinds of interesting things. Like asking PromptQL to identify areas to focus on for improving the project using the actual content from the GitHub issues. Or wiring it up to a support ticket system and billing data, and asking PromptQL to identify the customers that are at risk of churning and help me write customized emails to each of them.

I will mention, sometimes it gets specific SQL features or syntax support wrong for your data source. Other times it may time out on particularly huge or long running queries. However, a very neat feature is PromptQL will catch these issues, and with a feedback loop, it will attempt to self correct itself, which is pretty cool to witness. Other times, gentle steering by you can work around such issues.

Being able to understand what and why the Agent is behaving as it does are incredibly useful. Just as helpful is having what likens to a second set of eyes to help you along as you ask questions and explore, not to mention almost an expert level of SQL relevant to your schema.

Just like LEGO bricks, I've found PromptQL gives me the building blocks to construct meaning from data. Whether you're analyzing plastic bricks or production metrics, having a tool that shows its work and adapts to your schema is invaluable. I'd encourage anyone interested in LLMs, RAG, or Agentic flows to give it a try. And hey, even if you're just someone wanting to explore a dataset or thinking about giving your users a more natural way to ask questions about their data, you might find yourself building something pretty useful with PromptQL!

3 Guiding Principles for Building New SaaS Products on AWS

Jared Short — Tue, 05 May 2020 17:04:31 +0000

I won't start this article saying there is "one true-way" for building SaaS on cloud providers, specifically AWS. I will confidently say that there are many wrong ways. At Trek10, we find ourselves helping clients that have seen their AWS usage skyrocket and need to organize the chaos of an organic, home-grown crop of AWS Cloud. This article is distilled from years of working with folks at various points in their AWS journey in an effort to help guide you away from the wrong ways, and towards a successful path.

You know the story, and you may even have a part in the story yourself. A company is pivoting to the Software-as-a-Service model to modernize its offerings. Someone at the top hears that the cloud "accelerates the pace of innovation" and proclaims, "we must get on board or get left behind; this company won't be the laggards of the adoption curve!" If you are really on the cutting edge, an engineer or two has heard about this new "serverless" thing and is just plain tired of ssh-ing in and patching their fleet of "totally-automated everything away boss" EC2 instances.

Based on what I have seen and learned over the years, and some discussion with trusted colleagues, I want to talk about how I would (and in fact have) set up new organizations (products, SaaS, whathaveyou) from day one for future success. Here are a few guiding beacons to help you make the right long-term decisions.

Let's dive in.

#1 Build as if you may sell at any time

This may seem silly, especially if your organization has been around for a century. However, in new products and old companies alike the approach of building as if you may sell at any time has a similar effect; it forces you to build with best practices and isolation.

To achieve this goal, I’d lean on a few well known best practices, and perhaps some lesser-known tooling.

AWS Accounts are the ultimate unit of isolation

With the introduction of AWS Organizations, AWS made it clear that the multi-account strategy is the cut path in the deep jungles of account management. Stack on Control Tower and various Landing Zone offerings and you can rest assured that in this day and age you can easily leverage accounts for isolation in a practiced manner in even your most trivial projects.

These days, one of my favorite tools to orchestrate things is nothing more than a thin wrapper around native AWS tooling is AWS OrganizationFormation. OrgFormation works with a few simple tagging and logic schemes to set up accounts and deploy/maintain CloudFormation templates across them.

AWS Organizations also simplifies your technical auditing needs by centralizing AWS Config and GuardDuty.

The AWS account is also one of the most effective tools in your kit for blast radius limiting.

Finally, AWS Organizations centralizes your billing. Any sufficiently large cloud operation ends up requiring a Cloud Economist to make any sense of the madness, but with Organizations you can pretend to keep things under control for a while with the centralized billing as well as some simple alarms or dashboards.

A basic organization setup looks something like this.

Following this structure, you will note that each of the “products” is actually distributed into its own “organization unit” and each environment is broken up into its own AWS account. Billing, CI/CD and even Security & Auditing are centralized which can help maintain insight across the company.

Build for the cloud, in the cloud

This one may seem a bit odd, but let’s take a direct quote from my friend Ben Kehoe, Cloud Robotics Research Scientist and AWS Community Hero.

Move your development environment towards the cloud, do not try to move the cloud down to your dev environment.

There are an undeniable amount of tools and initiatives to bring familiar development cycles to local developer environments. Some are better than others. Some achieve more parity than others. As good as some of these are, inevitably you end up in a situation where something is not quite perfect and you spend days or weeks trying to work around that issue for your team. Even worse, you spend cycles debugging when something isn't quite right in your deployed cloud version.

These days, I personally do the majority of my development on AWS Cloud9. The fast, reliable internet on the box and what I'd call "good enough" feature set and language support are truly sufficient about 90% of the time.

In addition to Cloud9, I would also highly suggest either a shared "developer" AWS Sandbox account, or for more mature organizations a Sandbox per developer. If you are feeling extremely ambitious, maybe even ephemeral AWS accounts.

I'd ask most developers to start their day in Cloud9, and only eject to their local machines if they really need to. I would expect that they are doing unit tests or simple mocks locally to get their tests into a place where they are rapid and valuable locally, but that their real development and testing is pushing to their sandbox AWS accounts.

Simply put, there is no sufficient simulation or substitute for actual cloud resources.

This also encourages and requires good practice around integration and end-to-end testing.

#2 Build as if you may open-source at any time

This one is a bit more nuanced but let’s think about the decisions it forces us to make. We need to be a bit more introspective on our internal practices and scrutinize our codebase as if it is open to the world.

This means that security by obscurity, while never a good practice, is a definite no-go. We can’t rely on people not knowing we moved our admin endpoint to /unfindable-except-by-everyone. It also means no secrets strewed about in code, and no cert files stored in the repository.

Your project dependencies need to be regularly audited and remain up to date. You need to be able to roll-out new patched versions of your software soon after critical Common Vulnerabilities and Exposures (CVE) are released against those dependencies. The only way this is safe and feasible is with automated and comprehensive pipelines for deploying your code.

There is also the implied "embarrassment" angle. Sure, a little bit of sloppy coding is evident even in many open source projects. But knowing (or pretending) that some external force is looking over your shoulder may help you take the extra hour or two to properly pull out modules or add those tests you know should be done.

The final bit of advice that falls under this principle is documentation. An open-source project is only as good as its documentation. You could have the most elegant API in the world, but if there isn't enough documentation to communicate that point to new-comers there won't be anyone using your project. Good documentation extends beyond just your code or API. It encompasses your infrastructure practices, your guiding principles as a project, your on-boarding for new developers, and yes, your code and APIs.

#3 Build with a cloud-native mindset

Look ma’ my biases are showing! Clearly, I am an advocate for building with the tools provided by my platform of choice.

If AWS doesn't have it (or really, if CloudFormation doesn't support it) does it really exist? I get that this is a pretty aggressive, if not flippant, statement. However, any time I stray from a platform-native offering it's a reasonably high likelihood that I will regret it.

This also means leaning heavily into all the service offerings and orchestration tooling that is afforded to you by your platform. Don't be afraid to set some boundaries for your teams, but don't dogmatically enforce them.

As Alex DeBrie put it for me...

Provide standards but allow experimentation. AWS is a broad ecosystem, and there are some holes. Your company will choose some services and patterns that you prefer and others that you don't. Help your engineers understand what the preferred and supported patterns are. Make it clear that they can go off those paths, but they're going to be more on their own. This is akin to Charity's 'Golden Path' approach, but it's not really AWS specific.

To expand, there are certainly cases where staying within the platform isn't the most optimal solution. There are cases where the market is a few steps ahead of your platform provider. For instance, AWS doesn't have anything quite as tuned to fast frontend search experiences like Algolia. But the point remains that going outside of the platform should be an exception and something you do only when truly needed. While going out to the market isn't my first option, but it definitely fits with how I think about serverless still in 2020.

// Detect dark theme var iframe = document.getElementById('tweet-1100887501047132160-919'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1100887501047132160&theme=dark" }

Now, going out to the market and buying something doesn't always work out great. But my regret is lower than if I tried to build something in its place. To illustrate, I'll lean on my good friend Forrest Brazeal for the next thousand words.

Infrastructure as Code is one of the few "no compromise" issues

While writing for this piece, I reached out to 5 or so trusted folks to ask their guidance for organizations building on the cloud. Every single person explicitly stated that Infrastructure as Code (IaC) is an essential piece of the puzzle.

If you are not managing your infrastructure via CloudFormation, Terraform, or any of the other myriad of ways to model and deploy your infrastructure in repeatable ways you will eventually come to regret it. Whether you pay for it via needing to painstakingly rebuild a new environment as your application grows, or if you forget to check a box during a 3 hour manual deployment from staging to production and inexplicably bring down your application for a couple of harrowing hours.

If you take nothing else away from this post, please let it be that IaC is a cornerstone of a health product lifecycle on cloud.

Don't take my word for it

These 3 "guiding principles" are just that. Guidelines. They are not tenets that followed dogmatically guarantee success. They are in fact generalized snippets boiled out of some years of working with clients and on various AWS projects.

Evaluate every technology decision as a long term decision of partnership. Sure, you are billed by the second/day/month, but really you are electing to take on that technology as a partner in the growth of your SaaS. Some decisions are easier replaced than others, some choices you outgrow. That's natural and expected. In the same vein, don't evaluate your past choices in the current context. You will always know more now than you did then.

When it comes to those decisions, give your team authority and power to build and innovate. Don't shy away from the strengths of the cloud to augment your teams, and don't shy away from trusting your teams.

As Richard Boyd so eloquently put it for me...

Push authority down (don't push the CEO down a flight of stairs). A Software team that is responsible for the operational requirements of their application will drive the ops burden down. Typically this is done at an organizational level because Dev and Ops are separate teams/org. By forcing dev teams to own the ops of their applications, they have the responsibility (and the authority) to make changes in it that make the application more stable. Note, this is true in many places but it much more pronounced in the cloud where most software runs as a service

All said I'd build a new SaaS product without hesitation on AWS, and others should strongly consider it, but do so with a plan of action for your tech decisions and your teams.

3 Big Things I Wish Someone had Told Me When I Started Using AWS

Jared Short — Fri, 24 Apr 2020 17:17:56 +0000

I've been working with AWS for the past 6 years or so. I've run into many highs and lows during the work. With emotions ranging from feeling like a mythic god, bending the cloud to my will, to debating seeking a job doing something with my hands far away from a computer.

I introspected over the past years and asked a few co-workers and friends things that they wish they had known before they got started using AWS. I dug for more than "I wish I knew technology X better," because that is circumstantial and not all that helpful in many cases. Instead, view this compilation of observations by folks that have been in the cloud and things we think would have been nice to know.

AWS is a massive ecosystem. You can't understand it all, let alone be an expert in most of it.

In the early days when we were building Trek10 as a company (an AWS consulting shop), we dabbled in helping folks with Azure and other clouds. We quickly realized these projects drained resources and mental capacity, and simply put, distracted us from our ultimate goals of being recognized serverless and AWS experts. We decided to hyper-focus on our goals and reject all projects that didn't get us closer to that work.

On a personal level, this holds true for individuals as well. I make an effort to read at least one AWS service's documentation from cover to cover once a week. Rough calculations suggest I have spent 500+ hours just reading AWS service documentation (There are 221 doc repos on the official GitHub). I regularly reach out to AWS folks and colleagues for help understanding interactions between services, implications of a design choice, or even just an overview or refresher of a feature.

So don't take it personally on day 1 when nothing makes sense. This stuff is hard. My general suggestion is to have an end goal of what you want to build and break it into pieces you think are solvable by various services. Pick one service, read the docs cover to cover, and create that part to get your hit of endorphins. Then, wire that thing to a second service in the same manner.

Consider your knowledge base of AWS a living source. As features are added and best practices evolved, even what you knew a year ago may soon be obsolete. It's not bad, just a natural consequence of the cloud platform. Saying "I don't know, but I can find out" isn't a shameful thing, even to a client or boss.

Understanding a service's use-cases is very different than understanding the service.

I can tell you what most of the services on AWS do at a decent level of detail. Given a use case, I could probably rough out a couple of options for architectures pretty quickly. What I can't tell you is, based on exact needs, what problems you may run into with all of the service options that may fit. To do that, I would need to research service limits and other tidbits that are scattered around AWS documentation (notice a theme here yet?).

AWS Services have limits, both service limits and other functional restrictions. Usually they are quite reasonable, but other times, they will make your life genuinely miserable. Especially if your system needs to scale or evolve if you didn't consider things ahead of time.

For example, a real-world use case. Let's say you want to process a queue of transactions. We do some Googling and find that AWS has the Simple Queue Service (SQS). We look up limits and see we there can be 120,000 inflight messages by default and practically unlimited stored and incoming messages. Great, queue solved. To process the queue we can hook things up to AWS Lambda. Lambda will handle processing messages as they come in, so no messages mean no cost, and we can scale up to high volume transactions per second without much consideration.

Our system is humming along, but then we realize we are getting some problems in our backend during higher load times. Some numbers aren't adding up quite right. Ah, a race condition! Lambda and SQS do not guarantee order. We frantically search and find we can guarantee order with SQS FIFO (first in, first out). We are saved! Except... FIFO queues don't support Lambda function triggers. That's a heck of a limitation to run into this late in the project.

We are going to have to rearchitect or reconsider our whole set of service choices to address this problem (perhaps with Amazon Kinesis which can guarantee order and still works great with Lambda)!

You are going to get caught on sharp edges when you are exploring and learning. Your best defense is to review and re-review the limitations of the services before you choose them and ask in-depth questions about future states. Do we need to guarantee the order of anything? What size of payloads might we need? How many transactions per second if we are wildly successful? Do we need searchability of the data?

Inline bonus thing: AWS Improves around you

The AWS savvy among you may have been shouting at your screen "AWS Lambda Support FIFO Queues!" and you would be absolutely right. It does now. This wasn't the case a year ago. This brings me to the point that a proper solution today isn't the best solution tomorrow.

One of the unique properties of AWS (or the cloud in general), is that the services may improve around you. DynamoDB and S3 have addressed numerous pitfalls like hotkeys, scaling, etc. You'll see performance increases as AWS iterates on the underlying architectures. I've had solutions out in AWS Land that just got more performant or started costing less just based on AWS changes without me having to do anything.

Cost is really hard; leveraging the cloud is just as much about the business and people as it is the technology.

There are a lot of arguments for and against the cloud on cost models. Nearly every case I have read or heard toys around on raw pricing comparisons. On one end we have, "An EC2 instance on AWS costs $$$ per year, hardware in my data center amortized costs $$ per year. You are silly if you move to the cloud." With the other end saying, "Lambda functions cost $ per year, and I can serve a billion transactions without needing to order new hardware ever."

Most arguments don't dive into what it takes to build and maintain a data center, or staff folks in the data center or colo. What isn't talked about is the cost to retrain staff to leverage the cloud: the opportunity cost of pursuing cloud and retraining, or of building a data center and staffing developers to maintain internal systems just to keep the data center working.

While some of these conversations are starting to happen, I think the thing I wish I had realized was that cloud cost is less about optimizing raw infrastructure cost and more about optimizing opportunity, maintenance, and people costs. This frame of mind would have made a lot of conversations much smoother early in my career.

Corey Quinn, AWS Billing maverick explains it better than I can.
// Detect dark theme var iframe = document.getElementById('tweet-1101616132681752576-864'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1101616132681752576&theme=dark" } // Detect dark theme var iframe = document.getElementById('tweet-1101616133235339264-907'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1101616133235339264&theme=dark" }

Speed round

There was a lot to think about for this post. Here are some other things to consider.

Always, always practice good AWS account hygiene. Separate AWS accounts for environments and projects to get a built-in security blast radius and more effective costing practices.
AWS services sometimes aren't that practical or useful when they release, but they get progressively better. Check back on them as cases arise.
It's usually cheaper to try stuff out than do a ton of research, Proof-of-Concept early and often. Do it in a new account and with infrastructure as code so you can throw away the environment when you are done without losing any work.
There will be regional outages of services. This doesn't mean AWS is less available or stable than your data center. Build with these outages in mind. Review the AWS Well-Architected Framework. It will help you make better decisions from day 1.
Moving to cloud from traditional data centers is usually easier for developers than previously infrastructure and ops folks. Have a plan to turn your people into cloud natives, not just your services.
"Lift and Shift" is never as smart or short-term of a strategy as you want to believe.

From FaaS and Furious by Forrest Brazeal

I imagine there is a lot more someone could be told, more that I wish I had been told, but I can only hope to save someone a few troubles or moments of worry as they start their cloud journey. I'm always available on Twitter or in the comments to help!

An Intro to the Power of Serverless with AWS Amplify

Jared Short — Wed, 29 May 2019 14:41:56 +0000

A little story about serverless

Since 2014, my day job has been helping folks build and maintain stuff on Amazon Web Services (AWS). I've helped organizations from the most niche startups to household names on everything from real-time inventory management to machine learning on pizzas and everything in between.

I've seen containers get popular. I've seen the word Serverless get used so much that I am not even sure what it means anymore. One thing does remain for sure though, the real world Serverless systems I've been part of creating that have handled billions of transactions are some of the most pleasant to maintain and operate of any I've seen in my career.

So why do I love serverless, why does it matter? Y'all remember the Spectre/Meltdown insanity in early 2018 where chip level vulnerabilities were discovered, and everyone was freaking out and scrambling to fix it? The serverless environments I operated were patched before most orgs even had the conference rooms booked to build the response plan.

Here is a real depection of myself and the Trek10 team patching our Clients' serverless environments the night of the Spectre/Meltdown.

Some of my most fun tickets and replies of all time were along the lines of "Hello, we are from Company X's security team, and we need a full plan for maintenance and audits for the environment you maintain for us ASAP to address the recent security issues." Nothing like saying "already handled" with a link to the AWS patch notes completed before the vulnerability was even public.

At the end of the day, you want to deliver business value. You, too, can leverage the operations of the best and brightest in computing for pennies on the dollar by using serverless practices. Instead of worrying about server patching, networking, ssh keys, and the ilk, you get to focus on delivering your core value.

Tools of the Trade

There are a lot of options out there today from the Serverless Framework to Apex Up and many other providers and frameworks (many of them focusing on a niche use-case or language).

Most of my new projects kick off with AWS Amplify CLI these days. AWS Amplify CLI is somewhat of a wrapper on the complexities of the cloud, offering opinionated solutions while still offering customizability where you need.

Make sure you have Node.js 8.11.x or later and an AWS Account (don't worry about configuring anything yet, we simply need the account), and away we go.

Our project today is going to be a blast from the past, with a little twist. Remember those small "visitor counter" badges everyone used to have at the bottom of their website, usually right next to an animated gif of their countries flag?

Let's do that, but better... we are going to make it real-time™!

Start by installing the Amplify CLI with npm install -g @aws-amplify/cli and running amplify configure in your terminal. You'll be walked through various steps in a combination of your terminal and browser window, at the end of which you will have created and configured a new IAM user.

$ npm install -g @aws-amplify/cli
$ amplify configure
Follow these steps to set up access to your AWS account:

Sign in to your AWS administrator account:
https://console.aws.amazon.com/
Press Enter to continue

Specify the AWS Region
? region:  us-east-1
Specify the username of the new IAM user:
? user name:  captain-counter
Complete the user creation using the AWS console
https://console.aws.amazon.com/iam/home?region=undefined#/users$new?step=final&accessKey&userNames=captain-counter&permissionType=policies&policies=arn:aws:iam::aws:policy%2FAdministratorAccess
Press Enter to continue

Enter the access key of the newly created user:
? accessKeyId:  AKIAWTXIHO**********
? secretAccessKey:  AfGA3kTlGyv6F0GMyzQS********************
This would update/create the AWS Profile in your local machine
? Profile Name:  captain-counter

Successfully set up the new user.

Let's set up our project directory and initialize our amplify app.

$ mkdir counter && cd counter
$ amplify init
Note: It is recommended to run this command from the root of your app directory
? Enter a name for the project counter
? Enter a name for the environment dev
? Choose your default editor: Visual Studio Code
? Choose the type of app that you're building javascript
Please tell us about your project
? What javascript framework are you using none
? Source Directory Path:  src
? Distribution Directory Path: dist
? Build Command:  npm run-script build
? Start Command: npm run-script start
Using default provider  awscloudformation

For more information on AWS Profiles, see:
https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html

? Do you want to use an AWS profile? Yes
? Please choose the profile you want to use captain-counter
⠙ Initializing project in the cloud...

These steps (and mostly using default answers) will end up with a base amplify app running in your AWS account. It doesn't do much now, but let's keep coding. Do note; I opted not to use any particular framework. I want to keep this extremely lightweight since we'll be loading the script in other websites and there is no need for a framework where we are going.

Adding the API

Our little project wouldn't be very successful if we didn't have a way to track hits. We are going to leverage a GraphQL API with a service called AWS AppSync. AppSync is a fully managed GraphQL solution that allows you to quickly and easily map to various data sources, I've personally used it for many things, and it's everything it says on the label and then some.

$ amplify add api
? Please select from one of the below mentioned services: GraphQL
? Provide API name: counter
? Choose an authorization type for the API API key
? Do you have an annotated GraphQL schema? No
? Do you want a guided schema creation? No
? Provide a custom type name Counter
Creating a base schema for you...

Great, now let's open up amplify/backend/api/counter/schema.graphql and change the schema.

type Counter 
    @model
{
    id: String!
    hits: Int
}

Now for the fun part, let's deploy our API. Behind the scenes, Amplify compiles your schema to various queries and mutations, updates your CloudFormation templates to manage all the resources you need for your API, code generates a small client to access your API, and finally deploys everything via CloudFormation to your AWS account.

$ amplify push

Current Environment: dev

| Category | Resource name | Operation | Provider plugin   |
| -------- | ------------- | --------- | ----------------- |
| Api      | counter       | Create    | awscloudformation |
? Are you sure you want to continue? Yes

GraphQL schema compiled successfully.
Edit your schema at /Users/jshort/Work/counter/amplify/backend/api/counter/schema.graphql or place .graphql files in a directory at /Users/jshort/Work/counter/amplify/backend/api/counter/schema
? Do you want to generate code for your newly created GraphQL API Yes
? Choose the code generation language target javascript
? Enter the file name pattern of graphql queries, mutations and subscriptions src/graphql/**/*.js
? Do you want to generate/update all possible GraphQL operations - queries, mutations and subscriptions Yes
? Enter maximum statement depth [increase from default if your schema is deeply nested] 2
⠦ Updating resources in the cloud. This may take a few minutes...

....sometime later

GraphQL endpoint: https://ol2t5s4qlvbidcx2mwmigeya4m.appsync-api.us-east-1.amazonaws.com/graphql
GraphQL API KEY: da2-rbk5t2xpuvevlm6qza4onbly7m

At the end of the process, you'll get a GraphQL endpoint and API key. You can use these to start playing with and exploring your API immediately. Using something like GraphQL Playground or Insomnia may be the fastest way to play around with things.

Example configured GraphQL Playground, note the HTTP headers for authorization and all the pre-generated CRUD operations

If you check out your API, you will notice a TON of pre-built functionality for normal CRUD operations (Create, Read, Update, Delete). For our use-case, we don't need any of it, and we are going to substitute our own.

Change your amplify/backend/api/counter/schema.graphql to reflect this more locked down schema. We are taking away nearly all of the CRUD operations, renaming some of the operations, and adding a filtered subscription method. If you want to learn more about this, check out the AWS Amplify docs for GraphQL Transforms.

type Counter
    @model(
        queries: { get: "counter" },
        mutations: { create: "hit" },
        subscriptions: null
    )
{
    id: String!
    hits: Int
}

type Subscription {
    hits(id: String!): Counter
        @aws_subscribe(mutations: ["hit"])
}

Behind the scenes, Amplify is managing a DynamoDB table for us. A managed NoSQL database that can handle a tremendous load (In my experience one of the best serverless databases).

Next, We are going to customize our GraphQL resolver to take advantage of atomic updates within Amazon DynamoDB, meaning that every "hit" mutation for a counter, we increment the "hits" column by adding 1.

Amplify gives us a convenient way to override default resolver implementations with a resolvers folder in amplify/backend/api/counter/resolvers. Create a file call Mutation.hit.req.vtl and pop in the Velocity Template Language code below.

$util.qr($context.args.input.put("__typename", "Counter"))

#if( $util.isNullOrBlank($context.args.input.id) )
    $util.error("You MUST pass an `id` parameter")
#else

{
  "version": "2017-02-28",
  "operation": "UpdateItem",
  "key": {
      "id": $util.dynamodb.toDynamoDBJson($ctx.args.input.id)
  },
  "update": {
    "expression": "SET #typename = :typename ADD hits :one",
    "expressionNames": {
        "#typename": "__typename"
    },
    "expressionValues": {
        ":one": $util.dynamodb.toDynamoDBJson(1),
        ":typename": $util.dynamodb.toDynamoDBJson("Counter")
    }
  }
}
#end

Another quick amplify push (go ahead and agree to the prompts) grab yourself a beverage of choice and come back to a shiny new API ready for us to use.

Go ahead and try it out in your GraphQL Editor.

mutation{
  hit(input: {
    id: "test"
  }){
    id
    hits
  }
}

And you should get a response similar to this.

{
  "data": {
    "hit": {
      "id": "test",
      "hits": 118
    }
  }
}

Awesome. Next order of business, make ourselves a little counter.

cd src from your project root. You will see some other files and folder in there, like aws-exports.js and graphql. Create a new file called package.json with the following content.

{
  "name": "counter",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "parcel index.html"
  },
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "parcel-bundler": "^1.12.3"
  },
  "dependencies": {
    "aws-amplify": "^1.1.28"
  },
  "browserslist": [
    "last 2 Chrome versions"
  ]
}

Once you've got the file in place and saved run npm install, this may take a few minutes. As part of this, we are installing the aws-amplify Javascript SDK, as well as Parcel, a zero-config bundler so we can bundle up our module and leverage the SDK as well as making it easy to develop on later.

Don't give up now, we are almost there!

Alright, the final two bits before the big payoff.

First, create an index.html file in src.

<!DOCTYPE html>
<html>
<head>
    <title>Counter Widget</title>
</head>
<body>
    <div data-counter-id="test">Loading...</div>
    <script type="text/javascript" src="/index.js"></script>
</body>
</html>

We need this for Parcel to hook in to. Please note, you could be doing most of this in React, Vue, Svelte, and using WebPack or whatever floats your boat. Amplify SDK was leveraged and the rest of the code was written to keep things simple and illustrate the power behind the scenes, I am not trying to proselytize any particular frontend approach.

Finally, we have arrived at the big payoff. Let's create index.js in src as well.

import Amplify, { API, graphqlOperation } from 'aws-amplify';
import awsmobile from './aws-exports';

Amplify.configure(awsmobile);

import * as mutations from "./graphql/mutations";
import * as subscriptions from "./graphql/subscriptions";

/*
Find all the unique counter id on the page.
Send a single hit request for each unique ID.
Subscribe to all updates for each one as well.
*/

const init = function createUpdateCounters() {
    const countersToUpdate = document.querySelectorAll(`[data-counter-id]`);
    const counterHitIdSet = new Set();

    countersToUpdate.forEach((counter) => {
        counterHitIdSet.add(counter.dataset.counterId);
    })

    counterHitIdSet.forEach((id) => {
        hitCounter(id);
    });
}

/*
Send a mutation to your GraphQL to let it know we hit it.
This also means we get back the current count, including our own hit.
*/
async function hitCounter(id) {
    const counter = await API.graphql(graphqlOperation(mutations.hit, { input: { id } }));
    updateText(counter.data.hit)
    subscribeCounter(id)
}

function updateText(counter) {
    const countersToUpdate = document.querySelectorAll(`[data-counter-id=${counter.id}]`);
    countersToUpdate.forEach(function (elem) {
        elem.innerHTML = counter.hits;
    })
}

/*
Subscribe via WebSockets to all future updates for the counters
we have on this page.
*/
function subscribeCounter(id) {
    const subscription = API.graphql(
        graphqlOperation(subscriptions.hits, { id })
    ).subscribe({
        next: (counter) => updateText(counter.value.data.hits)
    });
}

// On dom loaded, kick things off
document.addEventListener("DOMContentLoaded", function () {
    init();
});

The comments contain most the hints about what is going on, but Amplify and GraphQL do a significant amount of the heavy lifting for us.

Go ahead and run npm start in the terminal and visit the URL it says your local dev server is started on. If everything works as expected, you should be able to see a counter after a brief Loading... message.

Open multiple tabs to see the counters increase as more hits accumulate, hit refresh once or twice to see that change propagate across all your open tabs in real-time.

Check out the little demo below, see how many visits have hit this page and codepen! Open it in a couple tabs and hit "rerun" button to watch real-time updates.

So, we made it! There are a couple of important takeaways to think about here. What we've done is running on production ready, massively scalable services. This can easily scale to thousands of requests per second (after lifting some default limits). Our actual code written was quite minimal, allowing Amplify to do the heavy lifting, not to mention everything is actually "infrastructure as code" which means we can create whole new app instances and environments on demand.

The mindset of serverless is all about offloading "undifferentiated heavy lifting", leveraging tools and services like AWS Amplify and AppSync get us closer to producing business value and further from managing infrastructure.