DEV Community: Ayrton Fidelis

The Great GraphQL Compass

Ayrton Fidelis — Thu, 05 Jan 2023 18:38:46 +0000

TLDR; Here's an organized collection of articles, guides and resources that you should be aware of when building GraphQL servers. Maybe hand the link to your team just in case.

Here's the link (it's free)

Why does this exist?

Have you ever shipped something and months later discovered some good piece of information that you wish you had early on, that would have saved you time, energy, money, that would make this thing you shipped more secure, reliable, pleasant to use?

As I was navigating my way through GraphQL development over the past years I've been collecting and organizing the resources that explained important concepts that shaped the way I design and implement GraphQL.

That's been a fundamental resource that I use when introducing GraphQL to individuals and teams and now I decided to share it here. Hope it helps you :)

Better results for product search on Elasticsearch

Ayrton Fidelis — Tue, 13 Apr 2021 01:51:00 +0000

Intro

This week we managed to significantly improve the search feature in one of the platforms of our company with a tricky but simple technique that took some considerable research time, and because it was really hard to find references about how to implement it I decided to write about what I found and maybe help some random dev out there, so here we go:

Scenario

First of all, we're talking about a "product search" feature. It happens by fetching products from a bunch of APIs and storing them in Elasticsearch to... you know... search.

These APIs often provide too little data to be searched on. Descriptions are too vague and breaf, titles are often confuse, no categorization, but that's not explainable to our users. When a user searches for "laptops", they mostly want a laptop, not a book about laptops or even a toy laptop.

That's where creativity entered into play.

Patterns arise

When brainstorming about ways to improve this product search, we whitnessed a pattern: the title of the products would most of the times start with it's name and follow with some characteristics and features, like in "Laptop Asus i7 8GB RAM", but the results that our users were getting included "Barbie Laptop" and "How to fix laptops - The definitive guide".

The user looking to buy laptops would often search for "laptops" or include a combination of desired characteristics like "laptop 16GB i7", so we realized that our users would get more relevant products in the first results if we increased the score of results that matched the first word of the search term with the first word of the product title. That's what we did.

The Span First Query

The right tool for this job would be the Span First Query, which matches "spans" near the beginning of a field. This query expects an end property that defines the number of terms in the beggining of the field to perform a query, and a match property that defines another Span Query to be performed against these first terms.

In this case we're looking to match terms, so we're using the Span Term Query. Here's what our final query looks like:

GET /products/_search
{
  "query": {
    "span_first": {
      "match": {
        "span_term": {
          "title": {
            "term": "laptops"
          }
        }
      },
      "end": 1
    }
  }
}

But the often overlooked detail about the Span Term Query is that it compares the term that we provide with the normalized tokens of the field (like when you store the words "Dog" and "dogs" and Elasticsearch lowercases and de-pluralize them, more details in this amazing video that anyone ever touching Elasticsearch should watch), but the Span Term Query expects the term that we provide to be already normalized, so we should take a step back and take a look at the Analyze API in order to achieve this.

Normalizing the search term

We need to turn the first word of our search string into a normalized token to be matched with the first term of the Span Query, and for that we use the Analyze API. We must be sure that the analyzer that's being used here is the same used when indexing the field that we'll be matching against. The easiest method to do that is to provide the name of the field to derive this setting from the field mapping.

GET /products/_analyze
{
  "field" : "title",
  "text" : "laptops"
}

The response of this request will contain information about the tokens:

{
  "tokens": [
    {
      "token": "laptop",
      "start_offset": 0,
      "end_offset": 6,
      "type": "word",
      "position": 0
    }
  ]
}

And this way we got out normalized token "laptop", which is what we must use in the Span Term Query. Remember this, it's important.

Now we need to embed our Span First query into the query that we're using to search for products and increase ther score of the results that match with this new clause of the query.

Using the Span First Query to boost our previous results

Here's a simplified version of our previous query, with a must property saying that all of our results must include the search term in the title, and a should property saying that results which include the search term in the description as well should have a higher score:

GET /products/_search
{
  "query": {
    "bool": {
      "must": [
        {
          "match": {
            "title": "laptops"
          }
        }
      ],
      "should": [
        {
          "match": {
            "description": "laptops"
          }
        }
      ]
    }
  }
}

To increase the score of results with matches on the first term, we'll put the span query on the should clause:

GET /products/_search
{
  "query": {
    "bool": {
      "must": [
        {
          "match": {
            "title": "laptops"
          }
        }
      ],
      "should": [
        {
          "match": {
            "description": "laptops"
          }
        },
        {
          "span_first": {
            "match": {
              "span_term": {
                "title": {
                  "term": "laptop"
                }
              }
            },
            "end": 1
          }
        }
      ]
    }
  }
}

The results

The results are great.

Our users now do find what they're looking for in the first products returned by our search feature. This change led to an increase in the value perception of our product and stakeholders are happy, but remember that this technique worked really well for the patterns detected in our data and our user's behavior, so do some investigation to see if it is the right solution for your use case.

Cover image from Andrea Piacquadio.

Best tip for GoLang programmers learning TypeScript

Ayrton Fidelis — Thu, 25 Mar 2021 18:06:28 +0000

I've been playing with GoLang recently, pretty cool language actually, but comming from a TypeScript world it was quite weird to me to use the nil keyword instead of null. I figured out that it could also be weird for Go devs learning TS, so here goes a little something to make the transition smoother:


const nil = null;

With that in place, Go devs are now able to use the familiar keyword instead of the longer alternative.

Building my personal website - Part 2 - The design

Ayrton Fidelis — Wed, 11 Mar 2020 21:59:37 +0000

Oh boy, here comes a tricky one.

As stated on the previous article, I've looked for content guidance, but proactively avoided any design inspiration. Even though I'm not a designer, I wanted to make this website as mine as possible.

Performance was a concern from the very beginning: I avoided using images as much as I could and used a pretty common font-face from Google Fonts, so that most users would have it cached already. You guessed it. It's Roboto.

The first thing I designed was a logo. I didn't know at that time, but it showed crucial on shaping the website as a whole. The final logo turned into something really simple: a colorful version of the website's domain.

Now we've got to a delicate point.

What the domain??!?#!%*?

Ok, I'll say it out loud: ayrtonvwf.dev.

Ask your mom to go to this website and watch her never being able to type it correctly.

The .dev part is pretty obvious, although non-dev folks would have a hard time believing that they've got it right.

"What? .dev? Is that a thing?"
– Non-dev person.

I've heard it a lot already, and it's not even deployed.

ayrtonvwf? My name concatenated to my initials. I've used it as a username on every social network since I started interneting. Easy for me to remember and it won't ever be taken by someone else before me, but it's a nightmare for other people to remember and that's a serious accessibility issue.

But, at the end of the day, I feel that it's uniqueness is what makes it work. It stands out. Most of the people will only click on a link rather than typing it, so I guess it's not a total disaster.

It's a bad decision that I don't regret.

Mostly important: I've chosen it in less than a week.

Don't start with a big bitmap image so that the first impression of the site will load instantly

That was my first challenge when I opened Figma to start the design. I've failed.

The user should understand right away that this website is about a person, a developer, rather than an enterprise or a single product. It felt so personal with a picture of an actual human being that I couldn't come back.

It feels like many websites glued together

It does.

The layout consists of the following sections:

Me
Personal Project 1
Personal Project 2
Contact info
Footnotes

Each Personal Project section feels like a separated website embedded into the main one. The first project is about security, so it feels bold and strong. The second one is about a lightweight layout, so it feels light and minimal.

In both cases, it's not me, a developer, talking about a product. It's the product presenting itself to the newcomer, with it's own personality and focusing on it's own features.

Building these so-different sections into my website is an arguable decision that I'm proud of making in less than a week.

It works.

The final design

It's finished.

I'll surely change some margins and font sizes as needed while implementing it, but it's finished. In less than a week.

One of my biggest challenges was not spending a whole month on every detail. I'm trying to finish a step and move to the next one before I get caught into a never ending loop. It's working.

Next step: Implementing a static website with no JS (and refusing to make it less of an website because of that).

Building my personal website - Part 1 - The content

Ayrton Fidelis — Fri, 21 Feb 2020 11:47:20 +0000

After I gave my first public tech talk, I finally felt confident enough to expose myself to the international dev community. And as I've just shut down two personal projects that were taking up my free time, I decided that time has come: I would build my personal website.

The first thing I did was look for articles about what a personal website should be like, specifically what content should it include. It was a good first step to the wrong direction.

A good first step to the wrong direction.

I avoided looking for design inspiration and focused on the content instead. After a bit of research I came up with a list.

A personal website must have:

Easy to find contact info
Downloadable Curriculum Vitae
A list of my strongest skills
My best personal projects
My personality

I started to prototype it, completely ignoring the list I've just made. With the first proposal finished I realized it had nothing to do with these items.

The fact is: that was somebody else's list. It includes what's important to other people who have already built their websites and written articles about it.

Realizing this I started to think about what my site should be. It must be a professional dev website, describing me and what I do, featuring some personal projects and my dev contact info.

I dropped the Curriculum Vitae: it should be personalized to a specific job position, featuring only relevant information.

The skills list? It just doesn't feel right to choose somethings and leaving others off of the plate. Should I put how much % of PHP I know? Should I separate Typescript from JS and SASS from CSS? Why bother? I decided that giving only the general context that I'm (mostly) a web developer would be the right thing to do.

Having the content in mind, I defined what's important to me on a good website in general. It should be fast, accessible, respecting the user preferences (dark mode, low motion, zoom) and should be simple. It must be totally static to be served by GitHub Pages.

It should have no JS. Ok, this last one is just a whim of mine.

Ancient browser support is not something that I'll be worried about. My public target (people interested in web development) is known for hating those entities.

Now that I knew what my site should be, it was time to start the design.

Spoiler: I'm not a designer.

A useful progress-bar fallback to IE9. CSS-only.

Ayrton Fidelis — Tue, 16 Oct 2018 00:05:13 +0000

Progress bars are tricky elements to be styled.

Yes, it's completely possible to make them look nice cross-browser with only CSS as this CSS-TRICKS post shows us. But making them look nice is not the point of this article.

The point of this article is making them useful for browsers that don't understand the progress element by themselves, and can't render that visible progress bar.

And it's simple.

Let's take a look at a basic progress markup:

<progress min="0" max="100" value="15"></progress>

To a browser that don't understand what progress means, it's just a HTMLUnknownElement with the properties min="0" max="100" value="15". What can we do with that?

Use :before and :after to inject the text 15/100 inside it:

/* make it look like a box */
progress {
  border: 1px solid black;
  line-height: 30px;
}  

/* make pseudo-elements 50% side-by-side */
progress:before, progress:after {
  display: inline-block;
  width: 50%;
}

/* put the value and a slash on the left half, aligned to the right */
progress:before {
  content: attr(value) '/';
  text-align: right;
}

/* put the max value on the right half */
progress:after {
  content: attr(max);
}

If we're sure that our progress elements will have a maximum of 100, we can show it with the % instead:

/* make it look like a box */
progress {
  border: 1px solid black;
  line-height: 30px;
}

/* put the value and the percent sign in the middle of the pseudo-element */
progress:before {
  content: attr(value) '%';
  display: block;
  text-align: center;
}

Here's a simple demo of the two situations working (with div instead of progress):

Here's this concept applied to that nice fully-styled progress-bar from that CSS-TRICKS post.