O que é o chunk() no Laravel?

Posted on: February 02, 2026 08:34 PM

Posted by: Renato

Views: 121

🚀 O que é o chunk() no Laravel?

O chunk() é um método do Eloquent/Query Builder que busca registros em blocos menores, ao invés de carregar tudo na memória de uma vez.

❌ O Problema do Model::all()

$users = User::all(); // carrega tudo em RAM de uma vez
  • 50 mil registros: já começa a pesar o servidor.
  • 500 mil registros: começa a doer a performance.
  • 5 milhões: vai derrubar seu worker, job ou container 😅

✅ Como usar chunk() na prática

O Laravel busca, processa e libera a memória automaticamente:

User::chunk(200, function ($users) {
    foreach ($users as $user) {
        // processa cada usuário
    }
});

📌 Por que usar?

🛡️

Estabilidade

Não estoura a RAM
📈

Escalabilidade

Lida com milhões de linhas
⚙️

Background

Ideal para Queues/Jobs

⚠️ Cuidado importante: use chunkById()

Se você atualiza ou deleta registros durante o loop, o chunk comum pode pular linhas. Use chunkById() para garantir a integridade.

🧠 Ponto de Senioridade

O "Combo de Produção" para arquivos gigantes:

Queue (Redis) Chunk Reading Batch Insert Progress Log

"Código que funciona é o mínimo. Código que escala é o que separa dev júnior de dev sênior."

🚀 O que é o chunk() no Laravel?

O chunk() é um método do Eloquent/Query Builder que busca registros em blocos menores, ao invés de carregar tudo na memória de uma vez.

❌ Problema do Model::all()

$users = User::all(); // carrega tudo em RAM

Se você tiver:

  • 50 mil registros → já pesa
  • 500 mil → começa a doer
  • 5 milhões → vai derrubar worker, job ou container 😅

✅ Como usar chunk() na prática

Exemplo básico:

User::chunk(200, function ($users) {
    foreach ($users as $user) {
        // processa cada usuário
    }
});

O que acontece aqui:

  • 1. Busca 200 registros
  • 2. Processa e libera da memória
  • 3. Busca os próximos 200
  • 4. Repete até acabar

📥 Exemplo real: importar Excel (50k linhas)

Processando uma tabela temporária:

TempImport::chunk(500, function ($rows) {
    foreach ($rows as $row) {
        User::updateOrCreate(
            ['email' => $row->email],
            ['name' => $row->name]
        );
    }
});
📌 Não estoura memória 📌 Não mata o worker 📌 Background safe

⚠️ Cuidado importante: use chunkById()

Se você atualiza ou deleta registros durante o processamento, o chunk() normal pode pular registros.

User::chunkById(200, function ($users) {
    foreach ($users as $user) {
        // processamento seguro
    }
});

🧠 Quando chunk() é obrigatório?

📊 Relatórios grandes
📥 Importações
🔄 Background
🧵 Jobs (queues)
🏗️ Migrações
🔁 Pesados

🧪 Alternativa econômica: cursor()

Para casos de leitura pura:

foreach (User::cursor() as $user) {
    // processa um por vez, quase zero memória
}
👉 Ótimo para exportações 👉 Não serve para lotes

Perfeito 😎 Exemplo de Produção Real

Arquitetura robusta para arquivos de 50k+ linhas

🧱 1️⃣ Tabela para controlar importações

Schema::create('imports', function (Blueprint $table) {
    $table->id();
    $table->string('file_path');
    $table->unsignedInteger('total_rows')->nullable();
    $table->unsignedInteger('processed_rows')->default(0);
    $table->enum('status', ['pending', 'processing', 'done', 'failed'])->default('pending');
    $table->text('error')->nullable();
    $table->timestamps();
});

📤 2️⃣ Controller (upload + criação do job)

public function import(Request $request) {
    $request->validate(['file' => 'required|file|mimes:xlsx,csv']);
    $path = $request->file('file')->store('imports');
    
    $import = Import::create([
        'file_path' => $path,
        'status' => 'pending',
    ]);

    ProcessExcelImport::dispatch($import->id);
    return response()->json(['import_id' => $import->id, 'message' => 'Background...']);
}

⚙️ 3️⃣ Job com controle de status

class ProcessExcelImport implements ShouldQueue {
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
    public function __construct(public int $importId) {}

    public function handle() {
        $import = Import::findOrFail($this->importId);
        $import->update(['status' => 'processing']);
        
        Excel::import(new UsersImport($import), $import->file_path, 'local');
        $import->update(['status' => 'done']);
    }

    public function failed(\Throwable $e) {
        Import::where('id', $this->importId)->update([
            'status' => 'failed',
            'error' => $e->getMessage(),
        ]);
    }
}

🔥 4️⃣ Batch Insert + Progresso (Performance Máxima)

class UsersImport implements OnEachRow, WithChunkReading {
    protected array $batch = [];
    public function __construct(protected Import $import) {}

    public function onRow(Row $row) {
        $data = $row->toArray();
        $this->batch[] = [
            'name' => $data[0],
            'email' => $data[1],
            'created_at' => now(), 'updated_at' => now(),
        ];

        if (count($this->batch) >= 1000) {
            User::insert($this->batch);
            $this->batch = [];
            $this->import->increment('processed_rows', 1000);
        }
    }

    public function __destruct() {
        if (!empty($this->batch)) {
            User::insert($this->batch);
            $this->import->increment('processed_rows', count($this->batch));
        }
    }

    public function chunkSize(): int { return 500; }
}

🎯 Resultado Final

  • ✅ Importação robusta
  • ✅ Escala arquivos gigantes
  • ✅ Feedback pro usuário
  • ✅ Workers estáveis
  • ✅ Zero risco de crash RAM
  • 💎 Código de Sênior

3

Share

Donate to Site


About Author

Renato

Developer

Add a Comment
Comments 0 Comments

No comments yet! Be the first to comment

Blog Search


Categories

Laravel (227) PHP (151) linux (124) Variados (110) ubuntu (58) Dicas (58) developer (48) postgresql (45) database (44) sql (42) Docker (32) front-end (31) mysql (31) devops (26) webdev (24) programming (23) tecnologia (19) eloquent (19) aws (19) dba (18) OUTROS (17) backend (16) laravelphp (16) debian (12) dev (12) 100DaysOfCode (10) git (10) react (10) reactjs (10) inteligencia-artificial (9) PHP Swoole (9) node (9) javascript (9) nginx (9) Architecture (8) linux-tools (8) vue (7) github (7) ciencia (7) webservice (6) jwt (6) vim (6) windows (6) arquitetura (6) nodejs (6) api (6) vscode (6) reactnative (5) rest (5) DevSecOps (5) servers (5) apache (5) macox (5) s3 (5) authentication (5) ia (5) shell (4) mongodb (4) angular (4) autenticacao (4) wsl (4) Swoole (4) lets-encrypt (4) query (4) Raspberry (4) angularjs (4) inteligenciadedados (4) Padrao de design (4) artigo (4) google (4) npm (4) openai (4) Kubernetes (4) gitlab (4) opensource (4) mariadb (4) jenkins (4) json (3) authorization (3) phpswoole (3) ddd (3) blade (3) terminal (3) log (3) mac (3) fedora (3) containers (3) ssh (3) bash (3) hardware (3) tests (3) macos (3) web (2) jobs (3) websocket (3) db (3) politica (3) js (3) mysqli (3) Black Hat (3) RabbitMQ (3) educacao (3) intel (3) CMS (2) sail (3) script (3) performance (3) bancodedados (2) tailwind (2) homeOffice (2) html (2) openswoole (2) artificialintelligence (2) security (2) seguranca (2) auth (2) cron (2) phpunit (2) kube (2) multiple_authen (2) policia (2) neovim (2) golang (2) noticias (2) livros (2) Transcribe (2) ElonMusk (2) redis (2) claude (2) ArchLinux (2) java (2) saude (1) phpfpm (2) autorizacao (2) monitoring (2) laptop (2) gnome (2) powerbi (2) telefonia (2) nvm (2) imagick (2) maps (2) colors (2) Passport (2) JQuery (2) Curisidades (2) Solid (2) zsh (2) Go (2) BigLinux (2) POO (2) LazyVim (2) gource (2) Python (2) Oauth2 (2) android (2) unix (2) magento (2) iot (2) ffmpeg (2) combustivel (2) webhook (2) microservices (2) Migration (1) workflow (1) cqrs (1) kitematic (1) geospacial (1) yeshua (1) data (1) sonarqube (1) Axios (1) pipelines (1) Mozilla (1) kvm (1) GitOps (1) sqlite (1) podcast (1) n8n (1) LaravelFilament (1) God (1) DesenvolvimentoProfissional (1) sw (1) bigtech (1) postgres (1) NoCookies (1) LeetCode (1) governancadedados (1) prf (1) nosql (1) Lideranca (1) Hackers (1) Bots (1) pytorch (1) nuxt (1) liquid (1) ec2 (1) transaction (1) c4 (1) rancher (1) algoritimo (1) Observability (1) Elasticsearch (1) translate (1) certbot (1) Oh My Zsh (1) ibm (1) escopos (1) usb (1) ckeditor (1) API_KEY_GOOGLE_MAPS (1) Manjaro (1) vicuna (1) coding (1) rust (1) markdown (1) JasperReports (1) Fibonacci (1) community (1) Samurai (1) payment (1) messaging (1) Jesus (1) flutter (1) militar (1) fullsta (1) smartphones (1) automacao (1) Monitor (1) zend (1) spaceship (1) PKCE (1) l2tp (1) Glacier (1) laraveloctane (1) Deus (1) binaural (1) gpt (1) bolsonaro (1) privacidade (1) linkedin (1) documentation (1) brain (1) adb (1) nvidia (1) host (1) ecommerce (1) c4-models (1) altadisponibilidade (1) octane (1) lucena (1) http (1) TypeScript (1) chatgpt (1) idiomas (1) eventdrive (1) uuid (1) restfull (1) aplicativo (1) optimization (1) mapas (1) Fetch (1) collections (1) RustLang (1) matematica (1) Filament (1) compactar (1) paypal (1) microg (1) forcas armadas (1) front (1) cor (1) auth (1) modelagemdedados (1) k8s (1) gasolina (1) wsl2 (1) csv (1) soap (1) piada (1) KubeCon (1) zorin-os (1) spring-boot (1) backup (1) playwright (1) Deepin (1) storage (1) benchmark (1) networking (1) Swoole (1) biologia (1) node-red (1) LETSENCRYPT (1) Grunt (1) Diagramas (1) boot (1) haru (1) dracula (1) TrabalhoEmEquipe (1) Brasil (1) queue (1) agi (1) llama (1) hotfix (1) economia (1) transcription (1) cache (1) Amazon (1) October (1) lumen (1) Hyperf (1) replication (1) faceapp (1) vala (1) cloudstack (1) rpi (1) apple (1) oracle (1) iode (1) ffaa (1) vpn (1) MeioAmbiente (1) firefox (1) composer (1) scheduling (1) Asahi (1) pendrive (1) microservice (1) front (1) wine (1) covid19 (0) services (1) phpjasper (1) models (1) kali-linux (1) geojson (1) yarn (1) picpay (1) Monolith (1) banco (1) PNPM (1) Desenvolvedor (1) Structurizr (1) symfony (1) presenter (1) lider (1) guard (1) tensorflow (1) bootstrap (1) nuance (1) historia (1) dropbox (1) traefik (1) bug (1) akitando (1) llm (1) htm (1) transformers (1) cavalotroia (1) odd (1) m1 (1) Error (1) cinnamon (1) repmgr (1) federal (1) ruby (1) AppSec (1) orm (1) ArquiteturaDeSoftware (1) Passwordless (1) memcached (1) flow (1) compression (1) athena (1) controllers (0) OOD (0)

New Articles



Get Latest Updates by Email