GraphQL::Client(3)

💅 GraphQL::Client — the Perl GraphQL client, bestie edition

okay so this is GraphQL::Client, a Perl module (manual name GraphQL::Client(3), in the User Contributed Perl Documentation section, if you're keeping track). Version? version 0.605. iconic. let's get into it 🎀

---

✨ SYNOPSIS ✨

the vibes, demonstrated:

my $graphql = GraphQL::Client->new(url => 'http://localhost:4000/graphql');

# Example: Hello world!

my $response = $graphql->execute('{hello}');

# Example: Kitchen sink

my $query = q[
    query GetHuman {
        human(id: $human_id) {
            name
            height
        }
    }
];
my $variables = {
    human_id => 1000,
};
my $operation_name = 'GetHuman';
my $transport_options = {
    headers => {
        authorization => 'Bearer s3cr3t',
    },
};
my $response = $graphql->execute($query, $variables, $operation_name, $transport_options);

# Example: Asynchronous with Mojo::UserAgent (promisify requires Future::Mojo)

my $ua = Mojo::UserAgent->new;
my $graphql = GraphQL::Client->new(ua => $ua, url => 'http://localhost:4000/graphql');

my $future = $graphql->execute('{hello}');

$future->promisify->then(sub {
    my $response = shift;
    ...
});

literally everything you need, right there 🫶

---

🌸 DESCRIPTION 🌸

GraphQL::Client gives you a simple way to execute GraphQL <https://graphql.org/> queries and mutations on a server. it's giving "just works."

this module is the programmatic interface, btw. there's also a CLI program if that's more your vibe.

GraphQL servers are usually served over HTTP, and the provided transport, GraphQL::Client::http, lets you plug in your own user agent — so this client works naturally with HTTP::Tiny, Mojo::UserAgent, and more. you can also use HTTP::AnyUA middleware. obsessed with the flexibility, ngl 💜

---

🦋 ATTRIBUTES 🦋

url

The URL of a GraphQL endpoint, e.g. http://myapiserver/graphql. main character address fr.

unpack

Whether or not to "unpack" the response, which enables a different style for error-handling.

Default is 0.

See "ERROR HANDLING" (below, keep scrolling bestie).

transport_class

The package name of a transport.

This is optional if the correct transport can be correctly determined from the url. the module's lowkey psychic like that ✨

transport

The transport object.

By default this is automatically constructed based on transport_class or url. no manual labor required 💅

---

👑 METHODS 👑

new

$graphql = GraphQL::Client->new(%attributes);

Construct a new client. slay, you have a client now.

execute

$response = $graphql->execute($query);
$response = $graphql->execute($query, \%variables);
$response = $graphql->execute($query, \%variables, $operation_name);
$response = $graphql->execute($query, \%variables, $operation_name, \%transport_options);
$response = $graphql->execute($query, \%variables, \%transport_options);

Execute a request on a GraphQL server, and get a response. the whole point, honestly.

By default, the response will either be a hashref with the following structure or a Future that resolves to such a hashref, depending on the transport and how it is configured.

{
    data   => {
        field1  => {...}, # or [...]
        ...
    },
    errors => [
        { message => 'some error message blah blah blah' },
        ...
    ],
}

Note: setting the unpack attribute affects the response shape. don't forget, bestie 😭

---

💀 ERROR HANDLING 💀

There are two different styles for handling errors. pick your fighter.

If unpack is 0 (off, the default), every response — whether success or failure — is enveloped like this:

{
    data   => {...},
    errors => [...],
}

where data might be missing or undef if errors occurred (though not necessarily) and errors will be missing if the response completed without error.

It is up to you to check for errors in the response, so your code might look like this:

my $response = $graphql->execute(...);
if (my $errors = $response->{errors}) {
    # handle $errors
}
else {
    my $data = $response->{data};
    # do something with $data
}

If unpack is 1 (on), then execute will return just the data if there were no errors, otherwise it will throw an exception. so your code would instead look like this:

my $data = eval { $graphql->execute(...) };
if (my $error = $@) {
    my $resp = $error->{response};
    # handle errors
}
else {
    # do something with $data
}

Or if you want to handle errors in a different stack frame, your code is simply this:

my $data = $graphql->execute(...);
# do something with $data

Both styles map to Future responses intuitively. If unpack is 0, the response always resolves to the envelope structure. If unpack is 1, successful responses will resolve to just the data and errors will fail/reject. no cap, it's that clean 🧚

---

🌈 SEE ALSO 🌈

• graphql — CLI program
• GraphQL — Perl implementation of a GraphQL server
• <https://graphql.org/> — GraphQL project website

---

🙈 BUGS 🙈

Please report any bugs or feature requests on the bugtracker website <https://github.com/chazmcgarvey/graphql-client/issues>

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. help them help you, bestie 🍓

---

⭐ AUTHOR ⭐

Charles McGarvey <ccm@cpan.org>

---

🎀 COPYRIGHT AND LICENSE 🎀

This software is copyright (c) 2020 by Charles McGarvey.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page, fr fr 💖 this was generated from perl v5.42.2, dated 2026-02-15 — go forth and query, icon 👑✨