Package: pluck-graphql
Pluck 🚀 🍊Pluck is a GraphQL client that transforms queries into Pandas data-frames.InstallationInstall Pluck fromPyPi:pipinstallpluck-graphqlIntroductionThe easiest way to get started is to usepluck.executeto execute a query.Let's read the first five SpaceX launches into a data-frame:importpluckSpaceX="https://main--spacex-l4uc6p.apollographos.net/graphql"query="""{launches(limit: 5) {mission_namelaunch_date_localrocket {rocket_name}}}"""frame,=pluck.execute(query,url=SpaceX)framelaunches.mission_namelaunches.launch_date_locallaunches.rocket.rocket_nameFalconSat2006-03-25T10:30:00+12:00Falcon 1DemoSat2007-03-21T13:10:00+12:00Falcon 1Trailblazer2008-08-03T15:34:00+12:00Falcon 1RatSat2008-09-28T11:15:00+12:00Falcon 1RazakSat2009-07-13T15:35:00+12:00Falcon 1Implicit ModeThe query above usesimplicit mode. This is where the entire response is normalized into a single data-frame.The return value fromexecuteis an instance ofpluck.Response. This object isiterableand enumerates the data-frames in the query. Because this query usesimplicit mode, the iterator contains only a single data-frame (note that the trailing comma is still required).@frame directiveBut Pluck is more powerful thanimplicit modebecause it provides a custom@framedirective.The@framedirective specifies portions of the GraphQL response that we want to transform into data-frames. The directive is removed before the query is sent to the GraphQL server.Using the same query, rather than use implicit mode, let's pluck thelaunchesfield from the response:query="""{launches(limit: 5) @frame {mission_namelaunch_date_localrocket {rocket_name}}}"""launches,=pluck.execute(query,url=SpaceX)launchesmission_namelaunch_date_localrocket.rocket_nameFalconSat2006-03-25T10:30:00+12:00Falcon 1DemoSat2007-03-21T13:10:00+12:00Falcon 1Trailblazer2008-08-03T15:34:00+12:00Falcon 1RatSat2008-09-28T11:15:00+12:00Falcon 1RazakSat2009-07-13T15:35:00+12:00Falcon 1The column names are no longer prefixed withlaunchesbecause it is now the root of the data-frame.Multiple @frame directivesWe can also pluck multiple data-frames from a single GraphQL query.Let's query the first five SpaceXrocketsas well:query="""{launches(limit: 5) @frame {mission_namelaunch_date_localrocket {rocket_name}}rockets(limit: 5) @frame {nametypecompanyheight {meters}mass {kg}}}"""launches,rockets=pluck.execute(query,url=SpaceX)Now we have the originallaunchesand a newrocketsdata-frame:rocketsnametypecompanyheight.metersmass.kgFalcon 1rocketSpaceX22.2530146Falcon 9rocketSpaceX70549054Falcon HeavyrocketSpaceX701420788StarshiprocketSpaceX1181335000ListsWhen a response includes a list, the data-frame is automatically expanded to include one row per item in the list. This is repeated for every subsequent list in the response.For example, let's query the first fiverocketsand theirpayload_weights:query="""{rockets(limit: 5) @frame {idtypenamepayload_weights {namekg}}}"""rockets,=pluck.execute(query,url=SpaceX)rocketsidtypenamepayload_weights.namepayload_weights.kg5e9d0d95eda69955f709d1ebrocketFalcon 1Low Earth Orbit4505e9d0d95eda69973a809d1ecrocketFalcon 9Low Earth Orbit228005e9d0d95eda69973a809d1ecrocketFalcon 9Geosynchronous Transfer Orbit83005e9d0d95eda69973a809d1ecrocketFalcon 9Mars Orbit40205e9d0d95eda69974db09d1edrocketFalcon HeavyLow Earth Orbit638005e9d0d95eda69974db09d1edrocketFalcon HeavyGeosynchronous Transfer Orbit267005e9d0d95eda69974db09d1edrocketFalcon HeavyMars Orbit168005e9d0d95eda69974db09d1edrocketFalcon HeavyPluto Orbit35005e9d0d96eda699382d09d1eerocketStarshipLow Earth Orbit1500005e9d0d96eda699382d09d1eerocketStarshipMars Orbit1000005e9d0d96eda699382d09d1eerocketStarshipMoon Orbit100000Rather than five rows, we have 11; each row contains a rocket and it's payload.Nested @frame directivesFrames can also be nested and if a nested@frameis within a list, the rows are combined into a single data-frame.For example, we can pluck the top fiverocketsandengines:query="""{rockets(limit: 5) @frame {idtypenameengines @frame {numbertypeversion}}}"""rockets,engines=pluck.execute(query,url=SpaceX)Now we have therockets:rocketsidtypenameengines.numberengines.typeengines.version5e9d0d95eda69955f709d1ebrocketFalcon 11merlin1C5e9d0d95eda69973a809d1ecrocketFalcon 99merlin1D+5e9d0d95eda69974db09d1edrocketFalcon Heavy27merlin1D+5e9d0d96eda699382d09d1eerocketStarship37raptorAnd we also have theenginesdata-frame that has been combined from every item inrockets:enginesnumbertypeversion1merlin1C9merlin1D+27merlin1D+37raptorAliasesColumn names can be modified using normal GraphQL aliases.For example, let's tidy-up the field names in thelaunchesdata-frame:query="""{launches(limit: 5) @frame {mission: mission_namelaunch_date: launch_date_localrocket {name: rocket_name}}}"""launches,=pluck.execute(query,url=SpaceX)launchesmissionlaunch_daterocket.nameFalconSat2006-03-25T10:30:00+12:00Falcon 1DemoSat2007-03-21T13:10:00+12:00Falcon 1Trailblazer2008-08-03T15:34:00+12:00Falcon 1RatSat2008-09-28T11:15:00+12:00Falcon 1RazakSat2009-07-13T15:35:00+12:00Falcon 1Column namesColumns are named according to the JSON path of the element in the response.However, we can use a different naming strategy by specifyingcolumn_namestoexecute.For example, let's useshortfor the column names:query="""{launches: launches(limit: 5) @frame {name: mission_namelaunch_date: launch_date_localrocket {rocket: rocket_name}}}"""launches,=pluck.execute(query,column_names="short",url=SpaceX)launchesnamelaunch_daterocketFalconSat2006-03-25T10:30:00+12:00Falcon 1DemoSat2007-03-21T13:10:00+12:00Falcon 1Trailblazer2008-08-03T15:34:00+12:00Falcon 1RatSat2008-09-28T11:15:00+12:00Falcon 1RazakSat2009-07-13T15:35:00+12:00Falcon 1If the short column name results in a conflict (two or more columns with the same name), the conflict is resolved by
prefixing the name with the name of it's parent.The naming strategy can also be changed per data-frame by specifying adict[str, str]where the key is name of the
data-frame.Leaf fieldsThe@framedirective can also be used on leaf fields.For example, we can extract only the name of the mission from past launches:query="""{launchesPast(limit: 5) {mission: mission_name @frame}}"""launches,=pluck.execute(query,url=SpaceX)launchesmissionFalconSatDemoSatTrailblazerRatSatRazakSatResponsesMost of the time, Pluck is used to transform the GraphQL query directly into one or more data-frames. However, it is also possible to retreive the the raw GraphQL response (as well as the data-frames) by not immeadiately iterating over the return value.The return value is apluck.Responseobject and contains thedataanderrorsfrom the raw GraphQL response and map ofDict[str, DataFrame]containing each data-frame in the query. The name of the frame corresponds to the field on which the@framedirective is placed ordefaultwhen using implicit mode.query="""{launches(limit: 5) @frame {idmission_namerocket {rocket_name}}landpads(limit: 5) @frame {idfull_namewikipedia}}"""response=pluck.execute(query,url=SpaceX)# print(response.data.keys())# print(response.errors)# print(response.frames.keys())launches,landpads=responselaunchesprint()landpadsidmission_namerocket.rocket_name5eb87cd9ffd86e000604b32aFalconSatFalcon 15eb87cdaffd86e000604b32bDemoSatFalcon 15eb87cdbffd86e000604b32cTrailblazerFalcon 15eb87cdbffd86e000604b32dRatSatFalcon 15eb87cdcffd86e000604b32eRazakSatFalcon 1idfull_namewikipedia5e9e3032383ecb267a34e7c7Landing Zone 1https://en.wikipedia.org/wiki/Landing_Zones_1_and_25e9e3032383ecb90a834e7c8Landing Zone 2https://en.wikipedia.org/wiki/Landing_Zones_1_and_25e9e3032383ecb554034e7c9Landing Zone 4https://en.wikipedia.org/wiki/Vandenberg_AFB_Space_Launch_Complex_4#LZ-4_landing_history5e9e3032383ecb6bb234e7caOf Course I Still Love Youhttps://en.wikipedia.org/wiki/Autonomous_spaceport_drone_ship5e9e3032383ecb761634e7cbJust Read The Instructions V1https://en.wikipedia.org/wiki/Autonomous_spaceport_drone_shippluck.createPluck also provides acreatefactory function which returns a customizedexecutefunction which closes over theurland other configuration.execute=pluck.create(url=SpaceX)query="""{launches(limit: 5) @frame {idmission_namerocket {rocket_name}}}"""launches,=execute(query)launchesidmission_namerocket.rocket_name5eb87cd9ffd86e000604b32aFalconSatFalcon 15eb87cdaffd86e000604b32bDemoSatFalcon 15eb87cdbffd86e000604b32cTrailblazerFalcon 15eb87cdbffd86e000604b32dRatSatFalcon 15eb87cdcffd86e000604b32eRazakSatFalcon 1